refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { rm } from "node:fs/promises";
|
||||
import process from "node:process";
|
||||
|
||||
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
|
||||
|
||||
/**
|
||||
* §17.2.2. Deterministic two-pass build.
|
||||
*
|
||||
* The Service Worker needs the exact hashed asset list at compile time, so the
|
||||
* order is fixed:
|
||||
*
|
||||
* 1. clean dist and .generated/frontend-runtime
|
||||
* 2. generate contractSet and build-info source
|
||||
* 3. Vite app build (emptyOutDir = true)
|
||||
* 4. materialize dist/config.json from the declared APP_PROFILE
|
||||
* 5. scan app dist and generate the static asset source
|
||||
* 6. ACTIVE only: Vite Service Worker build (emptyOutDir = false)
|
||||
* 7. generate Release Manifest V2 and the build manifest
|
||||
*
|
||||
* Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`
|
||||
* and `null`: those modes never run an active worker build.
|
||||
*
|
||||
* Step 4 has to follow the Vite build and precede the asset scan. Vite copies
|
||||
* `public/` verbatim, so without it every build — including a production one —
|
||||
* ships the local runtime document; and the Service Worker hashes the emitted
|
||||
* `config.json`, so the profile must be in place before that inventory is
|
||||
* taken.
|
||||
*/
|
||||
|
||||
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
|
||||
const buildsActiveWorker = selection?.mode === "ACTIVE";
|
||||
|
||||
function run(command: string, args: readonly string[]): void {
|
||||
const result = spawnSync(command, [...args], {
|
||||
stdio: "inherit",
|
||||
env: process.env,
|
||||
});
|
||||
if (result.status !== 0) {
|
||||
process.stderr.write(`build step failed: ${command} ${args.join(" ")}\n`);
|
||||
process.exit(result.status ?? 1);
|
||||
}
|
||||
}
|
||||
|
||||
// 1. clean
|
||||
await rm("dist", { recursive: true, force: true });
|
||||
await rm(".generated/frontend-runtime", { recursive: true, force: true });
|
||||
|
||||
// 2. contract set + build info
|
||||
run("node", ["scripts/generate-contract-set.ts"]);
|
||||
|
||||
// 3. app build
|
||||
run("npx", ["vite", "build"]);
|
||||
|
||||
// 4. runtime config for the declared profile
|
||||
run("node", ["scripts/generate-runtime-config.ts"]);
|
||||
|
||||
if (buildsActiveWorker) {
|
||||
// 5. hashed asset inventory
|
||||
run("node", ["scripts/generate-service-worker-assets.ts", "dist"]);
|
||||
// 6. service worker build
|
||||
run("npx", ["vite", "build", "--config", "vite.service-worker.config.ts"]);
|
||||
} else {
|
||||
process.stdout.write(
|
||||
`service worker mode ${selection?.mode ?? "null"}: skipping worker build\n`,
|
||||
);
|
||||
}
|
||||
|
||||
// 6. release + build manifest
|
||||
run("node", ["scripts/generate-build-manifest.ts"]);
|
||||
@@ -0,0 +1,248 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
import { readFileSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
import { CACHEABLE_ASSET_CONTENT_TYPES } from "../src/contracts/service-worker-static-manifest.ts";
|
||||
|
||||
/**
|
||||
* GOV-01 / SW-RR-03. Structural gates for facts that a hand-maintained document
|
||||
* cannot keep true.
|
||||
*
|
||||
* The adapter review inventory claimed 118/118 while the tree held 119 files,
|
||||
* so a whole adapter was outside every review's coverage without anything
|
||||
* failing. And the Service Worker asset generator and the shared manifest
|
||||
* decoder each carried their own extension table, so a build could emit an
|
||||
* asset the runtime contract then refused. Both are now equalities this script
|
||||
* checks rather than numbers someone has to remember to update.
|
||||
*/
|
||||
|
||||
const INVENTORY_PATH = "docs/reviews/adapters/INVENTORY.md";
|
||||
const GENERATOR_PATH = "scripts/generate-service-worker-assets.ts";
|
||||
|
||||
function trackedAdapterFiles(): readonly string[] {
|
||||
const listed = spawnSync("git", ["ls-files", "src/adapters"], {
|
||||
encoding: "utf8",
|
||||
});
|
||||
if (listed.status !== 0) {
|
||||
throw new Error(`git ls-files failed: ${listed.stderr}`);
|
||||
}
|
||||
return listed.stdout.split("\n").filter(Boolean).sort();
|
||||
}
|
||||
|
||||
function inventoryRows(markdown: string): readonly string[] {
|
||||
const rows: string[] = [];
|
||||
for (const line of markdown.split("\n")) {
|
||||
const match = /^\|\s*\d+\s*\|\s*`([^`]+)`\s*\|/u.exec(line);
|
||||
if (match?.[1]) rows.push(match[1]);
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
function reportDifference(
|
||||
label: string,
|
||||
expected: readonly string[],
|
||||
actual: readonly string[],
|
||||
): readonly string[] {
|
||||
const missing = expected.filter((value) => !actual.includes(value));
|
||||
const extra = actual.filter((value) => !expected.includes(value));
|
||||
const problems: string[] = [];
|
||||
for (const value of missing) problems.push(`${label}: missing ${value}`);
|
||||
for (const value of extra) problems.push(`${label}: unexpected ${value}`);
|
||||
return problems;
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const problems: string[] = [];
|
||||
|
||||
const tracked = trackedAdapterFiles();
|
||||
const markdown = await readFile(INVENTORY_PATH, "utf8");
|
||||
const listed = inventoryRows(markdown);
|
||||
problems.push(...reportDifference("adapter inventory", tracked, listed));
|
||||
if (listed.length !== new Set(listed).size) {
|
||||
problems.push("adapter inventory: duplicate row");
|
||||
}
|
||||
const total = /합계: \*\*(\d+)\/(\d+)\*\*/u.exec(markdown);
|
||||
if (
|
||||
!total ||
|
||||
Number(total[1]) !== tracked.length ||
|
||||
Number(total[2]) !== tracked.length
|
||||
) {
|
||||
problems.push(
|
||||
`adapter inventory: total does not equal ${tracked.length} tracked files`,
|
||||
);
|
||||
}
|
||||
|
||||
// SW-RR-03. The generator must read the shared table rather than declare one.
|
||||
const generator = await readFile(GENERATOR_PATH, "utf8");
|
||||
if (!generator.includes("CACHEABLE_ASSET_CONTENT_TYPES")) {
|
||||
problems.push(
|
||||
"service worker assets: generator does not use the shared extension table",
|
||||
);
|
||||
}
|
||||
if (/const CACHEABLE_EXTENSIONS[^=]*=\s*Object\.freeze\(\{/u.test(generator)) {
|
||||
problems.push(
|
||||
"service worker assets: generator declares its own extension table",
|
||||
);
|
||||
}
|
||||
for (const [extension, contentType] of Object.entries(
|
||||
CACHEABLE_ASSET_CONTENT_TYPES,
|
||||
)) {
|
||||
if (!extension.startsWith(".") || contentType.length === 0) {
|
||||
problems.push(`service worker assets: invalid table row ${extension}`);
|
||||
}
|
||||
}
|
||||
|
||||
// A fixture that links the repository's node_modules with a single directory
|
||||
// symlink is destructive: pnpm running inside that fixture purges the modules
|
||||
// directory it does not recognise, follows the link, and deletes the real
|
||||
// dependencies mid-run. `linkFixtureNodeModules` is the only sanctioned form.
|
||||
const sources = spawnSync(
|
||||
"git",
|
||||
["grep", "-n", "-e", 'symlink(', "--", "scripts", "tests"],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
if (sources.status === 0) {
|
||||
for (const line of sources.stdout.split("\n").filter(Boolean)) {
|
||||
if (!line.includes("node_modules")) continue;
|
||||
if (line.startsWith("scripts/lib/fixture-node-modules.ts:")) continue;
|
||||
problems.push(
|
||||
`fixture node_modules: use linkFixtureNodeModules instead — ${line}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
const linkedFixtures = spawnSync(
|
||||
"git",
|
||||
["grep", "-l", "linkFixtureNodeModules", "--", "scripts", "tests"],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
if (
|
||||
linkedFixtures.status !== 0 ||
|
||||
linkedFixtures.stdout.split("\n").filter(Boolean).length < 2
|
||||
) {
|
||||
problems.push(
|
||||
"fixture node_modules: the shared linker has no callers, so it is not the sanctioned path",
|
||||
);
|
||||
}
|
||||
|
||||
// TR-RR-05 / GOV-04. Every consumer the re-review named must use the shared
|
||||
// primitive, not merely one file somewhere. Checking `importers.length > 0`
|
||||
// let an unrelated production import satisfy the gate while Image and
|
||||
// Resumable kept their own diverging copies of the same mechanics — which is
|
||||
// exactly how the four hand-written versions drifted apart in the first place.
|
||||
//
|
||||
// 이 목록은 재검토가 이름으로 지목한 네 파일만 덮는다. 같은 두 그룹의
|
||||
// `image-cdn-runtime.ts`와 `resumable-upload-runtime.ts`는 여기 없고 지금도
|
||||
// 자기 abort 사본을 들고 있다. 어댑터 전체로는 23개 파일이 그렇다. 그 전수
|
||||
// 이행은 abort 의미론을 바꾸는 별도 작업이라 이 목록으로 강제하지 않고,
|
||||
// 아래 래칫이 개수가 늘어나는 것만 막는다.
|
||||
const REQUIRED_ABORT_CONSUMERS: readonly string[] = [
|
||||
"src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts",
|
||||
"src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts",
|
||||
"src/adapters/browser-transfer/image-cdn/browser-image-probe.ts",
|
||||
"src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts",
|
||||
];
|
||||
const primitiveImporters = spawnSync(
|
||||
"git",
|
||||
["grep", "-l", "platform/abortable-operation.ts", "--", "src"],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
const importers = (
|
||||
primitiveImporters.status === 0 ? primitiveImporters.stdout : ""
|
||||
)
|
||||
.split("\n")
|
||||
.filter(Boolean)
|
||||
.filter((file) => !file.endsWith("platform/abortable-operation.ts"))
|
||||
.sort();
|
||||
const importerSet = new Set(importers);
|
||||
const missingConsumers = REQUIRED_ABORT_CONSUMERS.filter(
|
||||
(consumer) => !importerSet.has(consumer),
|
||||
);
|
||||
if (missingConsumers.length > 0) {
|
||||
problems.push(
|
||||
`abortable-operation: required consumers do not import the shared primitive: ${missingConsumers.join(
|
||||
", ",
|
||||
)}`,
|
||||
);
|
||||
}
|
||||
// The importer must reach the primitive by a specifier that resolves to the
|
||||
// primitive itself, so a same-named local helper cannot satisfy the gate.
|
||||
const PRIMITIVE_PATH = path.resolve(
|
||||
"src/adapters/platform/abortable-operation.ts",
|
||||
);
|
||||
const PRIMITIVE_SPECIFIER = "platform/abortable-operation.ts";
|
||||
for (const consumer of REQUIRED_ABORT_CONSUMERS) {
|
||||
if (!importerSet.has(consumer)) continue;
|
||||
const source = readFileSync(consumer, "utf8");
|
||||
const specifiers = [
|
||||
...source.matchAll(/from\s+"([^"]*platform\/abortable-operation\.ts)"/gu),
|
||||
].map((match) => match[1] ?? "");
|
||||
const resolved = specifiers.some(
|
||||
(specifier) =>
|
||||
path.resolve(path.dirname(consumer), specifier) === PRIMITIVE_PATH,
|
||||
);
|
||||
if (!resolved) {
|
||||
problems.push(
|
||||
`abortable-operation: ${consumer} does not resolve its import to the shared primitive`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// 손수 짠 abort 배선은 줄어들기만 해야 한다.
|
||||
//
|
||||
// 커널 `platform/abortable-operation.ts`가 있는데도 어댑터 23개 파일이
|
||||
// `addEventListener("abort")`로 같은 race/cleanup을 각자 짠다. 그 전수 이행은
|
||||
// 동작이 바뀌는 큰 작업이라 한 번에 하지 않는다. 대신 개수를 여기 고정해
|
||||
// 되돌아가지 못하게 한다. 이행으로 숫자가 내려가면 이 상수도 같이 내린다.
|
||||
// `platform/`은 커널 자신이므로 세지 않는다.
|
||||
//
|
||||
// 24 → 23: `browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts`가
|
||||
// IndexedDB 커널로 옮겨가면서 자기 abort 리스너를 지웠다.
|
||||
// 23 → 22: `storage/indexeddb/indexeddb-maintenance.ts`가 같은 이유로 지웠다.
|
||||
// 22 → 21: `storage/indexeddb/indexeddb-runtime.ts`가 같은 이유로 지웠다.
|
||||
// 이것으로 IndexedDB 어댑터 4벌이 모두 커널을 쓴다.
|
||||
const HAND_ROLLED_ABORT_CEILING = 21;
|
||||
const handRolledScan = spawnSync(
|
||||
"git",
|
||||
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
const handRolledFiles = (
|
||||
handRolledScan.status === 0 ? handRolledScan.stdout : ""
|
||||
)
|
||||
.split("\n")
|
||||
.filter(Boolean)
|
||||
.filter((file) => !file.startsWith("src/adapters/platform/"))
|
||||
.filter((file) => !readFileSync(file, "utf8").includes(PRIMITIVE_SPECIFIER))
|
||||
.sort();
|
||||
if (handRolledFiles.length > HAND_ROLLED_ABORT_CEILING) {
|
||||
problems.push(
|
||||
`abortable-operation: hand-rolled abort wiring grew to ` +
|
||||
`${handRolledFiles.length} files (ceiling ${HAND_ROLLED_ABORT_CEILING}). ` +
|
||||
`Use platform/abortable-operation.ts instead of a new listener pair. ` +
|
||||
`Current offenders (the new one is whichever this change added): ` +
|
||||
`${handRolledFiles.join(", ")}`,
|
||||
);
|
||||
}
|
||||
|
||||
if (problems.length > 0) {
|
||||
for (const problem of problems) console.error(problem);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
// GOV-04. The exact importer set is part of the receipt, so a reviewer can
|
||||
// see which consumers the gate actually verified rather than a bare count.
|
||||
console.log(
|
||||
`Adapter inventory: ${tracked.length} files PASS; ` +
|
||||
`service worker asset table: ${
|
||||
Object.keys(CACHEABLE_ASSET_CONTENT_TYPES).length
|
||||
} shared extensions PASS; ` +
|
||||
`fixture node_modules linking PASS; ` +
|
||||
`shared abort primitive: ${importers.length} importers ` +
|
||||
`(${importers.join(", ")}) PASS; ` +
|
||||
`hand-rolled abort wiring: ${handRolledFiles.length}/` +
|
||||
`${HAND_ROLLED_ABORT_CEILING} files (ratchet) PASS`,
|
||||
);
|
||||
}
|
||||
|
||||
await main();
|
||||
@@ -0,0 +1,143 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
createFileSystemDeclarationSource,
|
||||
type TopologyDeclarationSource,
|
||||
} from "./generate-product-feature-index.ts";
|
||||
|
||||
/**
|
||||
* Spec §3 / §37. Build-input regression gate for deployable-app isolation.
|
||||
*
|
||||
* The app being built is the one recorded in `src/.generated/product-app.ts`.
|
||||
* Its allowed features are exactly those owned (via their context) by that
|
||||
* app's declarations. The gate fails when
|
||||
* - a generated index imports a feature or declares a context outside that
|
||||
* ownership set (e.g. a regression back to "import every src/features"),
|
||||
* - the production bundle's module inventory contains a module of a feature
|
||||
* the app does not own.
|
||||
*/
|
||||
export type AppBuildInputReport = Readonly<{
|
||||
appId: string;
|
||||
ownedContexts: readonly string[];
|
||||
ownedFeatureDirectories: readonly string[];
|
||||
generatedFeatureImports: readonly string[];
|
||||
generatedContexts: readonly string[];
|
||||
bundle: Readonly<{ checked: boolean; featureDirectories: readonly string[] }>;
|
||||
violations: readonly string[];
|
||||
}>;
|
||||
|
||||
const GENERATED = [
|
||||
"src/.generated/product-feature-index.ts",
|
||||
"src/.generated/product-context-index.ts",
|
||||
"src/.generated/product-app.ts",
|
||||
] as const;
|
||||
|
||||
function unique(values: Iterable<string>): string[] {
|
||||
return [...new Set(values)].sort();
|
||||
}
|
||||
|
||||
export async function inspectAppBuildInput(
|
||||
root: string,
|
||||
options: Readonly<{
|
||||
source?: TopologyDeclarationSource;
|
||||
bundleInventory?: string | null;
|
||||
}> = {},
|
||||
): Promise<AppBuildInputReport> {
|
||||
const source = options.source ?? (await createFileSystemDeclarationSource(root));
|
||||
const [featureIndex, contextIndex, appIndex] = await Promise.all(
|
||||
GENERATED.map((file) => readFile(path.join(root, file), "utf8")),
|
||||
);
|
||||
const appId = /id:\s*"([^"]+)"/u.exec(appIndex ?? "")?.[1];
|
||||
const violations: string[] = [];
|
||||
if (!appId || !source.app(appId)) {
|
||||
violations.push(`generated app ${appId ?? "<missing>"} is not a declared deployable app`);
|
||||
}
|
||||
const ownedContexts = appId ? source.contextsOf(appId).map((context) => context.id) : [];
|
||||
const ownedFeatureDirectories = unique(
|
||||
ownedContexts.flatMap((contextId) => source.featuresOf(contextId).map((feature) => feature.directory)),
|
||||
);
|
||||
const owned = new Set(ownedFeatureDirectories);
|
||||
|
||||
const featureDirectoriesIn = (text: string) =>
|
||||
unique([...text.matchAll(/\.\.\/features\/([^/"']+)\//gu)].map((match) => match[1] as string));
|
||||
const generatedFeatureImports = unique([
|
||||
...featureDirectoriesIn(featureIndex ?? ""),
|
||||
...featureDirectoriesIn(contextIndex ?? ""),
|
||||
]);
|
||||
for (const directory of generatedFeatureImports) {
|
||||
if (!owned.has(directory)) {
|
||||
violations.push(`generated index imports feature "${directory}" not owned by app ${appId}`);
|
||||
}
|
||||
}
|
||||
const generatedContexts = unique(
|
||||
[...(contextIndex ?? "").matchAll(/defineBoundedContextModule\(\{\s*id:\s*"([^"]+)"/gu)].map(
|
||||
(match) => match[1] as string,
|
||||
),
|
||||
);
|
||||
const ownedContextSet = new Set(ownedContexts);
|
||||
for (const contextId of generatedContexts) {
|
||||
if (!ownedContextSet.has(contextId)) {
|
||||
violations.push(`generated index declares context "${contextId}" not owned by app ${appId}`);
|
||||
}
|
||||
}
|
||||
|
||||
let bundle: AppBuildInputReport["bundle"] = { checked: false, featureDirectories: [] };
|
||||
const inventoryPath =
|
||||
options.bundleInventory === undefined
|
||||
? path.join(root, "artifacts/quality/vite-module-inventory.json")
|
||||
: options.bundleInventory;
|
||||
if (inventoryPath) {
|
||||
const raw = await readFile(inventoryPath, "utf8").catch(() => null);
|
||||
if (raw !== null) {
|
||||
const inventory = JSON.parse(raw) as { chunks?: { modules?: string[] }[] };
|
||||
const modules = (inventory.chunks ?? []).flatMap((chunk) => chunk.modules ?? []);
|
||||
const featureDirectories = unique(
|
||||
modules.flatMap((module) => {
|
||||
const match = /^src\/features\/([^/]+)\//u.exec(module);
|
||||
return match ? [match[1] as string] : [];
|
||||
}),
|
||||
);
|
||||
bundle = { checked: true, featureDirectories };
|
||||
for (const directory of featureDirectories) {
|
||||
if (!owned.has(directory)) {
|
||||
violations.push(`production bundle contains feature "${directory}" not owned by app ${appId}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
appId: appId ?? "",
|
||||
ownedContexts: unique(ownedContexts),
|
||||
ownedFeatureDirectories,
|
||||
generatedFeatureImports,
|
||||
generatedContexts,
|
||||
bundle,
|
||||
violations,
|
||||
});
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
// The bundle inventory is only meaningful right after a build of this tree;
|
||||
// without `--require-bundle` the gate checks the generated indexes only, so a
|
||||
// stale inventory from another build can never pass or fail it.
|
||||
const requireBundle = process.argv.includes("--require-bundle");
|
||||
const report = await inspectAppBuildInput(process.cwd(), requireBundle ? {} : { bundleInventory: null });
|
||||
if (requireBundle && !report.bundle.checked) {
|
||||
process.stderr.write("app build input: no production module inventory; run the build first\n");
|
||||
process.exit(1);
|
||||
}
|
||||
for (const violation of report.violations) process.stderr.write(`FAIL ${violation}\n`);
|
||||
process.stdout.write(
|
||||
`app build input: app=${report.appId} contexts=${report.ownedContexts.length} ` +
|
||||
`features=${report.ownedFeatureDirectories.length} generatedImports=${report.generatedFeatureImports.length} ` +
|
||||
`bundle=${report.bundle.checked ? `${report.bundle.featureDirectories.length} feature dirs` : "not checked"} ` +
|
||||
`${report.violations.length === 0 ? "PASS" : "FAIL"}\n`,
|
||||
);
|
||||
if (report.violations.length > 0) process.exitCode = 1;
|
||||
}
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
await main();
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,207 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { readFile, readdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
function requiredPnpmCli(): string {
|
||||
const executable = process.env.npm_execpath;
|
||||
if (!executable) {
|
||||
throw new Error(
|
||||
"check:browser-file-storage-boundaries must run through pnpm",
|
||||
);
|
||||
}
|
||||
return executable;
|
||||
}
|
||||
|
||||
function runEslint(path: string) {
|
||||
return spawnSync(
|
||||
process.execPath,
|
||||
[
|
||||
requiredPnpmCli(),
|
||||
"exec",
|
||||
"eslint",
|
||||
path,
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
}
|
||||
|
||||
function runEslintSource(source: string, virtualPath: string) {
|
||||
return spawnSync(
|
||||
process.execPath,
|
||||
[
|
||||
requiredPnpmCli(),
|
||||
"exec",
|
||||
"eslint",
|
||||
"--stdin",
|
||||
"--stdin-filename",
|
||||
virtualPath,
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
],
|
||||
{ encoding: "utf8", input: source },
|
||||
);
|
||||
}
|
||||
|
||||
const allowed = runEslint(
|
||||
"tests/fixtures/browser-file-storage-boundaries/allowed",
|
||||
);
|
||||
const forbiddenRoot =
|
||||
"tests/fixtures/browser-file-storage-boundaries/forbidden";
|
||||
const forbiddenFiles = (
|
||||
await readdir(forbiddenRoot, { withFileTypes: true })
|
||||
)
|
||||
.filter((entry) => entry.isFile() && /\.tsx?$/u.test(entry.name))
|
||||
.map((entry) => path.join(forbiddenRoot, entry.name));
|
||||
const forbiddenResults = forbiddenFiles.map((file) => ({
|
||||
file,
|
||||
result: runEslint(file),
|
||||
}));
|
||||
const acceptedForbidden = forbiddenResults.filter(
|
||||
({ result }) => result.status === 0,
|
||||
);
|
||||
const indexedDbBypassSource = await readFile(
|
||||
path.join(forbiddenRoot, "direct-indexeddb.ts"),
|
||||
"utf8",
|
||||
);
|
||||
const objectUrlBypassSource = await readFile(
|
||||
path.join(forbiddenRoot, "object-url.ts"),
|
||||
"utf8",
|
||||
);
|
||||
const blobBypassSource = await readFile(
|
||||
path.join(forbiddenRoot, "direct-blob.ts"),
|
||||
"utf8",
|
||||
);
|
||||
const crossContextAdapterSource = await readFile(
|
||||
"tests/fixtures/browser-file-storage-boundaries/allowed/cross-context-host.ts",
|
||||
"utf8",
|
||||
);
|
||||
const browserStorageAdapterSource = await readFile(
|
||||
"tests/fixtures/browser-file-storage-boundaries/allowed/browser-storage-host.ts",
|
||||
"utf8",
|
||||
);
|
||||
const protectedSourceFixtureNames = [
|
||||
"aliased-globalthis.ts",
|
||||
"class-field-alias.ts",
|
||||
"constructor-root-escape.ts",
|
||||
"default-parameter-alias.ts",
|
||||
"direct-blob.ts",
|
||||
"dynamic-capability-key.ts",
|
||||
"global-object-container.ts",
|
||||
"identity-wrapped-global.ts",
|
||||
"instance-property-alias.ts",
|
||||
"property-descriptor-access.ts",
|
||||
] as const;
|
||||
const protectedSourceFixtures = await Promise.all(
|
||||
protectedSourceFixtureNames.map(async (file) => ({
|
||||
file,
|
||||
source: await readFile(path.join(forbiddenRoot, file), "utf8"),
|
||||
})),
|
||||
);
|
||||
const approvedAdapterResults = [
|
||||
{
|
||||
file: "src/adapters/storage/indexeddb/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
indexedDbBypassSource,
|
||||
"src/adapters/storage/indexeddb/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/adapters/cross-context-invalidation/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
crossContextAdapterSource,
|
||||
"src/adapters/cross-context-invalidation/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/adapters/storage/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
browserStorageAdapterSource,
|
||||
"src/adapters/storage/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/adapters/browser-transfer/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
blobBypassSource,
|
||||
"src/adapters/browser-transfer/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
];
|
||||
const rejectedApprovedAdapters = approvedAdapterResults.filter(
|
||||
({ result }) => result.status !== 0,
|
||||
);
|
||||
const misplacedAdapterResults = [
|
||||
{
|
||||
file: "src/adapters/http/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
indexedDbBypassSource,
|
||||
"src/adapters/http/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/features/reference-feature/adapters/boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
objectUrlBypassSource,
|
||||
"src/features/reference-feature/adapters/boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/adapters/http/cross-context-boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
crossContextAdapterSource,
|
||||
"src/adapters/http/cross-context-boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
{
|
||||
file: "src/adapters/http/browser-storage-boundary-fixture.ts",
|
||||
result: runEslintSource(
|
||||
browserStorageAdapterSource,
|
||||
"src/adapters/http/browser-storage-boundary-fixture.ts",
|
||||
),
|
||||
},
|
||||
...protectedSourceFixtures.map(({ file, source }) => {
|
||||
const virtualPath = `src/presentation/${file}`;
|
||||
return {
|
||||
file: virtualPath,
|
||||
result: runEslintSource(source, virtualPath),
|
||||
};
|
||||
}),
|
||||
];
|
||||
const acceptedMisplacedAdapters = misplacedAdapterResults.filter(
|
||||
({ result }) => result.status === 0,
|
||||
);
|
||||
|
||||
if (
|
||||
allowed.status !== 0 ||
|
||||
rejectedApprovedAdapters.length > 0 ||
|
||||
forbiddenFiles.length === 0 ||
|
||||
acceptedForbidden.length > 0 ||
|
||||
acceptedMisplacedAdapters.length > 0
|
||||
) {
|
||||
process.stderr.write(allowed.stderr || allowed.stdout);
|
||||
for (const { file, result } of rejectedApprovedAdapters) {
|
||||
process.stderr.write(
|
||||
`${file}: owned browser capability adapter was rejected\n`,
|
||||
);
|
||||
process.stderr.write(result.stderr || result.stdout);
|
||||
}
|
||||
for (const { file, result } of acceptedForbidden) {
|
||||
process.stderr.write(
|
||||
`${file}: forbidden browser API fixture was accepted\n`,
|
||||
);
|
||||
process.stderr.write(result.stderr || result.stdout);
|
||||
}
|
||||
for (const { file, result } of acceptedMisplacedAdapters) {
|
||||
process.stderr.write(
|
||||
`${file}: native browser storage access outside its owned adapter was accepted\n`,
|
||||
);
|
||||
process.stderr.write(result.stderr || result.stdout);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`Browser file/storage boundaries: PASS (owned adapter allowed, ${forbiddenFiles.length + misplacedAdapterResults.length} direct or misplaced native access cases rejected)\n`,
|
||||
);
|
||||
@@ -0,0 +1,49 @@
|
||||
import { readdir } from "node:fs/promises";
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
function requiredPnpmCli(): string {
|
||||
const executable = process.env.npm_execpath;
|
||||
if (!executable) {
|
||||
throw new Error("check:browser-security must run through the pnpm script");
|
||||
}
|
||||
return executable;
|
||||
}
|
||||
|
||||
const pnpmCli = requiredPnpmCli();
|
||||
|
||||
function runPnpm(arguments_: string[]) {
|
||||
return spawnSync(process.execPath, [pnpmCli, ...arguments_], {
|
||||
encoding: "utf8",
|
||||
});
|
||||
}
|
||||
|
||||
const allowed = runPnpm([
|
||||
"exec",
|
||||
"eslint",
|
||||
"tests/fixtures/security/allowed",
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
]);
|
||||
const forbidden = runPnpm([
|
||||
"exec",
|
||||
"eslint",
|
||||
"tests/fixtures/security/forbidden",
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
]);
|
||||
|
||||
const distFiles = await readdir("dist", { recursive: true });
|
||||
const publicSourceMaps = distFiles.filter((file) => String(file).endsWith(".map"));
|
||||
|
||||
if (allowed.status !== 0 || forbidden.status === 0 || publicSourceMaps.length > 0) {
|
||||
process.stderr.write(allowed.stderr || allowed.stdout);
|
||||
process.stderr.write(forbidden.stderr || forbidden.stdout);
|
||||
if (publicSourceMaps.length > 0) {
|
||||
process.stderr.write(`Public source maps found: ${publicSourceMaps.join(", ")}\n`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
"Browser security fixtures: injection rejected, public source maps absent\n",
|
||||
);
|
||||
@@ -0,0 +1,109 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.ts";
|
||||
import {
|
||||
bundleOutputInventoryArtifactSchema,
|
||||
bundlePerformanceArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { classifyViteJavascript } from "./lib/classify-vite-bundle.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type ViteManifest = Record<
|
||||
string,
|
||||
{ file: string; isEntry?: boolean; imports?: string[] }
|
||||
>;
|
||||
type BundleBudgets = {
|
||||
initialJsGzipBytes: number;
|
||||
lazyChunkGzipBytes: number;
|
||||
};
|
||||
|
||||
const report = bundleOutputInventoryArtifactSchema.parse(
|
||||
JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8")) as unknown,
|
||||
);
|
||||
const viteManifest = JSON.parse(
|
||||
await readFile("dist/.vite/manifest.json", "utf8"),
|
||||
) as ViteManifest;
|
||||
const budgets = JSON.parse(
|
||||
await readFile("config/performance/budgets.json", "utf8"),
|
||||
).bundle as BundleBudgets;
|
||||
|
||||
const outputByPath = new Map(
|
||||
report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
|
||||
);
|
||||
const classification = classifyViteJavascript(viteManifest);
|
||||
const initialJsGzipBytes = classification.initialFiles.reduce(
|
||||
(total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
|
||||
0,
|
||||
);
|
||||
const lazyChunks = classification.lazyFiles.map((file) => ({
|
||||
path: file,
|
||||
gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
|
||||
}));
|
||||
const missingOutputs = [
|
||||
...classification.initialFiles,
|
||||
...classification.lazyFiles,
|
||||
].filter((file) => !outputByPath.has(file));
|
||||
const measurements = { initialJsGzipBytes, lazyChunks };
|
||||
const result = evaluateBundleBudget(measurements, budgets);
|
||||
const fixtures = [
|
||||
{
|
||||
name: "initial-js-over-budget",
|
||||
passed:
|
||||
!evaluateBundleBudget(
|
||||
{
|
||||
initialJsGzipBytes: budgets.initialJsGzipBytes + 1,
|
||||
lazyChunks: [],
|
||||
},
|
||||
budgets,
|
||||
).passed,
|
||||
},
|
||||
{
|
||||
name: "lazy-chunk-over-budget",
|
||||
passed:
|
||||
!evaluateBundleBudget(
|
||||
{
|
||||
initialJsGzipBytes: 0,
|
||||
lazyChunks: [
|
||||
{
|
||||
path: "fixture.js",
|
||||
gzipBytes: budgets.lazyChunkGzipBytes + 1,
|
||||
},
|
||||
],
|
||||
},
|
||||
budgets,
|
||||
).passed,
|
||||
},
|
||||
];
|
||||
const passed =
|
||||
result.passed &&
|
||||
fixtures.every((fixture) => fixture.passed) &&
|
||||
classification.missingImports.length === 0 &&
|
||||
missingOutputs.length === 0;
|
||||
const completedReport = {
|
||||
...report,
|
||||
measurements,
|
||||
classification,
|
||||
missingOutputs,
|
||||
thresholds: budgets,
|
||||
results: result,
|
||||
fixtures,
|
||||
passed,
|
||||
};
|
||||
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/performance/bundle.json",
|
||||
schema: bundlePerformanceArtifactSchema,
|
||||
value: completedReport,
|
||||
});
|
||||
if (!passed) {
|
||||
process.stderr.write(
|
||||
`Bundle budget or manifest integrity failed: ${[
|
||||
...classification.missingImports,
|
||||
...missingOutputs,
|
||||
].join(", ")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes)\n`,
|
||||
);
|
||||
@@ -0,0 +1,142 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import {
|
||||
evaluatePromotionReadiness,
|
||||
PROMOTION_FORMULA,
|
||||
type GateResult,
|
||||
} from "../src/application/policies/promotion-readiness.ts";
|
||||
import {
|
||||
loadCiGateContract,
|
||||
indexCiGateContract,
|
||||
} from "./contracts/ci-gates.ts";
|
||||
import { generateCiWorkflow, renderCiWorkflow } from "./generate-ci-workflow.ts";
|
||||
import {
|
||||
ciContractReportSchema,
|
||||
} from "./lib/ci-contract-report.ts";
|
||||
import {
|
||||
validateInstallScriptPolicy,
|
||||
validatePackageScriptGraph,
|
||||
} from "./lib/package-script-graph.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const removalFixtureMode = process.argv.includes("--reduced-removal-fixture");
|
||||
const contract = await loadCiGateContract(process.cwd(), {
|
||||
mode: removalFixtureMode ? "removal-fixture" : "canonical",
|
||||
});
|
||||
const index = indexCiGateContract(contract);
|
||||
const [packageDocument, nodeVersion] = await Promise.all([
|
||||
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
|
||||
readFile(".nvmrc", "utf8").then((value) => value.trim()),
|
||||
]);
|
||||
const packageScripts = packageDocument.scripts ?? {};
|
||||
const failures: string[] = [];
|
||||
|
||||
if (!/^\d+\.\d+\.\d+$/u.test(nodeVersion)) {
|
||||
failures.push(".nvmrc must contain one exact Node.js semantic version");
|
||||
}
|
||||
for (const script of [
|
||||
"build:release-candidate",
|
||||
"verify:local-evidence",
|
||||
"verify:promotion",
|
||||
"generate:ci-workflow",
|
||||
"check:ci-workflow",
|
||||
"check:ci",
|
||||
]) {
|
||||
if (!packageScripts[script]) failures.push(`package script missing ${script}`);
|
||||
}
|
||||
for (const removedScript of [
|
||||
"build:release",
|
||||
"verify:supply-chain",
|
||||
"verify:supply-chain:promotion",
|
||||
]) {
|
||||
if (packageScripts[removedScript]) failures.push(`legacy package script remains ${removedScript}`);
|
||||
}
|
||||
if (/\b(?:build|rebuild)(?::[\w-]+)?\b/u.test(packageScripts["verify:promotion"] ?? "")) {
|
||||
failures.push("verify:promotion must not build or rebuild candidate bytes");
|
||||
}
|
||||
failures.push(...validatePackageScriptGraph(packageScripts, "check:ci"));
|
||||
failures.push(
|
||||
...validateInstallScriptPolicy(
|
||||
packageScripts,
|
||||
[...new Set(contract.commands.map(({ script }) => script))],
|
||||
),
|
||||
);
|
||||
|
||||
const immutable = index.gates.get("FE-GATE-015");
|
||||
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
|
||||
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
|
||||
failures.push("FE-GATE-015 must build candidate bytes once and verify local evidence only");
|
||||
}
|
||||
const architecture = index.gates.get("FE-GATE-010");
|
||||
if (!architecture?.commandIds.some((id) => index.commands.get(id)?.script === "check:ci")) {
|
||||
failures.push("a blocking gate must execute check:ci");
|
||||
}
|
||||
if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.path === "artifacts/quality/ci-contract.json")) {
|
||||
failures.push("FE-GATE-010 must publish the typed CI contract report");
|
||||
}
|
||||
|
||||
const expectedGateIds = Array.from(
|
||||
{ length: 27 },
|
||||
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
|
||||
);
|
||||
const passingResults: Record<string, GateResult> = Object.fromEntries(
|
||||
expectedGateIds.map((gateId) => [gateId, "PASS"]),
|
||||
);
|
||||
const allPass = evaluatePromotionReadiness(passingResults);
|
||||
const negativeFixtures: Array<{
|
||||
readiness: keyof typeof PROMOTION_FORMULA;
|
||||
failedGate: string;
|
||||
passed: boolean;
|
||||
}> = [];
|
||||
for (const readiness of Object.keys(PROMOTION_FORMULA) as Array<keyof typeof PROMOTION_FORMULA>) {
|
||||
const failedGate = PROMOTION_FORMULA[readiness][0];
|
||||
if (!failedGate) throw new TypeError(`${readiness} has no configured gates`);
|
||||
const evaluated = evaluatePromotionReadiness({ ...passingResults, [failedGate]: "FAIL" });
|
||||
const passed = evaluated[readiness] === false;
|
||||
negativeFixtures.push({ readiness, failedGate, passed });
|
||||
if (!passed) failures.push(`${readiness} did not fail closed`);
|
||||
}
|
||||
if (!Object.values(allPass).every(Boolean)) failures.push("all-PASS formula did not produce every readiness state");
|
||||
|
||||
const renderedWorkflow = renderCiWorkflow(contract);
|
||||
const workflowCheck = await generateCiWorkflow({
|
||||
root: process.cwd(),
|
||||
contract,
|
||||
check: true,
|
||||
});
|
||||
if (!workflowCheck.matches) {
|
||||
failures.push(
|
||||
`generated workflow drift at byte ${workflowCheck.firstDifferenceByte ?? "missing"}, line ${workflowCheck.firstDifferenceLine ?? "missing"}`,
|
||||
);
|
||||
}
|
||||
let checkedWorkflowBytes = Buffer.from(renderedWorkflow, "utf8");
|
||||
try {
|
||||
checkedWorkflowBytes = await readFile(workflowCheck.target);
|
||||
} catch (error) {
|
||||
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
const report = ciContractReportSchema.parse({
|
||||
schemaVersion: 2,
|
||||
nodeVersion,
|
||||
gateCount: contract.gates.length,
|
||||
commandDefinitionCount: contract.commands.length,
|
||||
commandReferenceCount: contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0),
|
||||
artifactCount: contract.artifacts.length,
|
||||
jobCount: contract.jobs.length,
|
||||
workflowSha256: createHash("sha256").update(checkedWorkflowBytes).digest("hex"),
|
||||
durationStatus: contract.retention.durationStatus,
|
||||
negativeFixtures,
|
||||
failures,
|
||||
passed: failures.length === 0,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/quality/ci-contract.json",
|
||||
schema: ciContractReportSchema,
|
||||
value: report,
|
||||
});
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("CI contract: 27 gates, strict v2 graph and generated workflow model PASS\n");
|
||||
@@ -0,0 +1,58 @@
|
||||
import { mkdir, readFile } from "node:fs/promises";
|
||||
|
||||
import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts";
|
||||
import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type CompatibilitySchema = Readonly<{
|
||||
required?: readonly string[];
|
||||
properties?: Readonly<Record<string, unknown>>;
|
||||
}>;
|
||||
|
||||
type CompatibilityFixture = Readonly<{
|
||||
before: CompatibilitySchema;
|
||||
after: CompatibilitySchema;
|
||||
}>;
|
||||
|
||||
type CompatibilityFixtures = Readonly<{
|
||||
families: Readonly<
|
||||
Record<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
|
||||
>;
|
||||
}>;
|
||||
|
||||
const fixtures = JSON.parse(
|
||||
await readFile("config/compatibility/fixtures.json", "utf8"),
|
||||
) as CompatibilityFixtures;
|
||||
const results = [];
|
||||
|
||||
for (const [family, cases] of Object.entries(fixtures.families)) {
|
||||
for (const expected of ["additive", "breaking"] as const) {
|
||||
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 writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/compatibility.json",
|
||||
schema: compatibilityFixturesArtifactSchema,
|
||||
value: {
|
||||
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,
|
||||
},
|
||||
});
|
||||
|
||||
if (results.some((result) => !result.passed)) {
|
||||
process.stderr.write("Compatibility fixture classification failed.\n");
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("Compatibility fixtures: PASS\n");
|
||||
@@ -0,0 +1,149 @@
|
||||
import { mkdir, readFile, readdir } from "node:fs/promises";
|
||||
|
||||
import { designSystemReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import path from "node:path";
|
||||
|
||||
import { REQUIRED_COMPONENT_TOKENS, REQUIRED_PRIMITIVE_TOKENS, REQUIRED_SEMANTIC_TOKENS } from "../src/presentation/design-system/tokens/token-contract.ts";
|
||||
|
||||
const fixtureMode = process.argv.includes("--fixture");
|
||||
const failures: string[] = [];
|
||||
const tokenFiles = {
|
||||
primitive: "src/presentation/design-system/tokens/primitive.css",
|
||||
semantic: "src/presentation/design-system/tokens/semantic.css",
|
||||
component: "src/presentation/design-system/tokens/component.css",
|
||||
};
|
||||
const tokenLayers: Array<readonly [string, string, readonly string[]]> = [
|
||||
["primitive", tokenFiles.primitive, REQUIRED_PRIMITIVE_TOKENS],
|
||||
["semantic", tokenFiles.semantic, REQUIRED_SEMANTIC_TOKENS],
|
||||
["component", tokenFiles.component, REQUIRED_COMPONENT_TOKENS],
|
||||
];
|
||||
|
||||
for (const [layer, file, tokens] of tokenLayers) {
|
||||
const source = await readFile(file, "utf8");
|
||||
for (const token of tokens) {
|
||||
if (!source.includes(`${token}:`)) {
|
||||
failures.push(`${layer} token is missing: ${token}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const cssSources = await Promise.all(
|
||||
[...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(
|
||||
async (file) => ({ file, source: await readFile(file, "utf8") }),
|
||||
),
|
||||
);
|
||||
const definitions = new Set(
|
||||
cssSources.flatMap(({ source }) =>
|
||||
[...source.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1]),
|
||||
),
|
||||
);
|
||||
for (const { file, source } of cssSources) {
|
||||
for (const match of source.matchAll(/var\((--[a-z0-9-]+)/g)) {
|
||||
if (!definitions.has(match[1])) {
|
||||
failures.push(`${file} uses undefined token ${match[1]}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const semanticSource = await readFile(tokenFiles.semantic, "utf8");
|
||||
const darkSource =
|
||||
semanticSource.match(/:root\[data-theme="dark"\]\s*\{([\s\S]*?)\n\}/)?.[1] ??
|
||||
"";
|
||||
for (const token of [
|
||||
"--color-surface",
|
||||
"--color-surface-muted",
|
||||
"--color-surface-elevated",
|
||||
"--color-content",
|
||||
"--color-content-muted",
|
||||
"--color-content-inverse",
|
||||
"--color-border",
|
||||
"--color-border-strong",
|
||||
"--color-action",
|
||||
"--color-action-hover",
|
||||
"--color-action-pressed",
|
||||
"--color-danger",
|
||||
"--color-focus",
|
||||
"--color-disabled-content",
|
||||
"--color-disabled-surface",
|
||||
]) {
|
||||
if (!darkSource.includes(`${token}:`)) {
|
||||
failures.push(`dark theme token is missing: ${token}`);
|
||||
}
|
||||
}
|
||||
const componentSource = await readFile(tokenFiles.component, "utf8");
|
||||
if (!componentSource.includes("@media (forced-colors: active)")) {
|
||||
failures.push("forced-colors token fallback is missing");
|
||||
}
|
||||
|
||||
async function listSourceFiles(directory: string): Promise<string[]> {
|
||||
const result: string[] = [];
|
||||
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
||||
const target = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
|
||||
else if (/\.(?:ts|tsx|mts|cts)$/.test(entry.name)) result.push(target);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
const sources = fixtureMode
|
||||
? await listSourceFiles("tests/fixtures/design-system/forbidden")
|
||||
: await listSourceFiles("src");
|
||||
for (const file of sources) {
|
||||
const source = await readFile(file, "utf8");
|
||||
const vendorFacade =
|
||||
file === "src/presentation/design-system/icons/vendors/lucide.tsx";
|
||||
if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) {
|
||||
failures.push(`direct icon vendor import in ${file}`);
|
||||
}
|
||||
if (
|
||||
/from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
|
||||
) {
|
||||
failures.push(`direct headless vendor import in ${file}`);
|
||||
}
|
||||
if (
|
||||
!file.includes("src/presentation/design-system/") &&
|
||||
/presentation\/design-system\/(?!index(?:\.tsx?)?["'])/.test(source)
|
||||
) {
|
||||
failures.push(`design-system deep import in ${file}`);
|
||||
}
|
||||
if (
|
||||
!file.includes("src/presentation/design-system/tokens/") &&
|
||||
/(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source)
|
||||
) {
|
||||
failures.push(`raw palette value in ${file}`);
|
||||
}
|
||||
if (
|
||||
file.includes("tests/fixtures/design-system/forbidden") &&
|
||||
source.includes("TOOLTIP_ONLY_REQUIRED_INFORMATION")
|
||||
) {
|
||||
failures.push(`tooltip-only required information in ${file}`);
|
||||
}
|
||||
}
|
||||
|
||||
const report = designSystemReportArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
mode: fixtureMode ? "negative-fixture" : "source",
|
||||
checkedTokenCount:
|
||||
REQUIRED_PRIMITIVE_TOKENS.length +
|
||||
REQUIRED_SEMANTIC_TOKENS.length +
|
||||
REQUIRED_COMPONENT_TOKENS.length,
|
||||
failures,
|
||||
passed: failures.length === 0,
|
||||
});
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: fixtureMode
|
||||
? "artifacts/quality/design-system-fixture.json"
|
||||
: "artifacts/quality/design-system.json",
|
||||
schema: designSystemReportArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(`Design system contract failed:\n${failures.join("\n")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`,
|
||||
);
|
||||
@@ -0,0 +1,140 @@
|
||||
import { mkdir, readFile, readdir } from "node:fs/promises";
|
||||
|
||||
import { diagnosticsReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
DIAGNOSTIC_CONTEXT_ALLOWLIST,
|
||||
DIAGNOSTIC_CONTEXT_CARDINALITY,
|
||||
DIAGNOSTIC_EVENT_REGISTRY,
|
||||
} from "../src/contracts/diagnostics.ts";
|
||||
import {
|
||||
TELEMETRY_ATTRIBUTE_ALLOWLIST,
|
||||
TELEMETRY_REGISTRY,
|
||||
} from "../src/contracts/telemetry.ts";
|
||||
|
||||
const fixtureMode = process.argv.includes("--fixture");
|
||||
const failures: string[] = [];
|
||||
const extensions = /\.(?:ts|tsx|mts|cts)$/;
|
||||
|
||||
async function filesBelow(directory: string): Promise<string[]> {
|
||||
const result: string[] = [];
|
||||
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
||||
const target = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) result.push(...(await filesBelow(target)));
|
||||
else if (extensions.test(entry.name)) result.push(target);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
const telemetryProducerFiles: Readonly<Record<string, string>> = {
|
||||
"app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
|
||||
"api.request.failed": "src/adapters/http/client.ts",
|
||||
"ui.render.failed": "src/application/create-application.ts",
|
||||
"release.mismatch.detected": "src/application/create-application.ts",
|
||||
"telemetry.delivery.dropped":
|
||||
"src/adapters/telemetry/best-effort-telemetry.ts",
|
||||
};
|
||||
const diagnosticProducerFiles: Readonly<Record<string, string>> = {
|
||||
"app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
|
||||
"http.request.completed": "src/adapters/http/client.ts",
|
||||
"cache.operation.failed":
|
||||
"src/adapters/query-cache/tanstack-query-cache.ts",
|
||||
"storage.operation.failed":
|
||||
"src/adapters/storage/browser-storage-adapter.ts",
|
||||
"route.changed": "src/application/create-application.ts",
|
||||
"ui.render.failed": "src/application/create-application.ts",
|
||||
"release.mismatch.detected": "src/application/create-application.ts",
|
||||
"telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts",
|
||||
};
|
||||
|
||||
for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) {
|
||||
if (!DIAGNOSTIC_CONTEXT_CARDINALITY[key]) {
|
||||
failures.push(`diagnostic context key has no cardinality class: ${key}`);
|
||||
}
|
||||
}
|
||||
for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) {
|
||||
// Defensive at runtime: the types already exclude it, the gate still checks.
|
||||
const cardinality: string | undefined = DIAGNOSTIC_CONTEXT_CARDINALITY[key];
|
||||
if (cardinality === "request") {
|
||||
failures.push(`request-cardinality telemetry attribute is forbidden: ${key}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (!fixtureMode) {
|
||||
for (const eventName of Object.keys(TELEMETRY_REGISTRY)) {
|
||||
const producer = telemetryProducerFiles[eventName];
|
||||
if (!producer) {
|
||||
failures.push(`telemetry event has no declared producer: ${eventName}`);
|
||||
continue;
|
||||
}
|
||||
const source = await readFile(producer, "utf8");
|
||||
if (!source.includes(`"${eventName}"`)) {
|
||||
failures.push(`telemetry producer is not executable: ${eventName}`);
|
||||
}
|
||||
}
|
||||
for (const eventId of Object.keys(DIAGNOSTIC_EVENT_REGISTRY)) {
|
||||
const producer = diagnosticProducerFiles[eventId];
|
||||
if (!producer) {
|
||||
failures.push(`diagnostic event has no declared producer: ${eventId}`);
|
||||
continue;
|
||||
}
|
||||
const source = await readFile(producer, "utf8");
|
||||
if (!source.includes(`"${eventId}"`)) {
|
||||
failures.push(`diagnostic producer is not executable: ${eventId}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const sources = fixtureMode
|
||||
? await filesBelow("tests/fixtures/diagnostics/forbidden")
|
||||
: await filesBelow("src");
|
||||
const sensitiveContext =
|
||||
/\b(?:authorization|cookie|access_token|refresh_token|request_body|response_body|raw_url|query_string|email|user_name)\b/i;
|
||||
for (const file of sources) {
|
||||
const source = await readFile(file, "utf8");
|
||||
if (file.includes("contracts/telemetry.ts")) continue;
|
||||
if (source.includes("console.")) {
|
||||
failures.push(`direct console diagnostics bypass in ${file}`);
|
||||
}
|
||||
const calls = source.match(
|
||||
/(?:\.record\(\{|\.emit\()[\s\S]{0,700}?(?:\}\)|\}\);)/g,
|
||||
) ?? [];
|
||||
if (calls.some((call) => sensitiveContext.test(call))) {
|
||||
failures.push(`sensitive diagnostic or telemetry context in ${file}`);
|
||||
}
|
||||
if (
|
||||
file.includes("tests/fixtures/diagnostics/forbidden") &&
|
||||
source.includes("UNKNOWN_DIAGNOSTIC_EVENT")
|
||||
) {
|
||||
failures.push(`unknown diagnostic event in ${file}`);
|
||||
}
|
||||
}
|
||||
|
||||
const report = diagnosticsReportArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
mode: fixtureMode ? "negative-fixture" : "source",
|
||||
telemetryEventCount: Object.keys(TELEMETRY_REGISTRY).length,
|
||||
diagnosticEventCount: Object.keys(DIAGNOSTIC_EVENT_REGISTRY).length,
|
||||
checkedFiles: sources.length,
|
||||
failures,
|
||||
passed: failures.length === 0,
|
||||
});
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: fixtureMode
|
||||
? "artifacts/quality/diagnostics-fixture.json"
|
||||
: "artifacts/quality/diagnostics.json",
|
||||
schema: diagnosticsReportArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(
|
||||
`Diagnostics contract failed:\n${failures.join("\n")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Diagnostics contract: ${report.diagnosticEventCount} diagnostics and ${report.telemetryEventCount} telemetry producers PASS\n`,
|
||||
);
|
||||
@@ -0,0 +1,39 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
const fixtureRoot = await mkdtemp(
|
||||
path.join(tmpdir(), "ca-frontend-frozen-lockfile-"),
|
||||
);
|
||||
try {
|
||||
await cp("pnpm-lock.yaml", path.join(fixtureRoot, "pnpm-lock.yaml"));
|
||||
const manifest = JSON.parse(await readFile("package.json", "utf8"));
|
||||
manifest.dependencies.react = "0.0.0-invalid-fixture";
|
||||
await writeFile(
|
||||
path.join(fixtureRoot, "package.json"),
|
||||
`${JSON.stringify(manifest, null, 2)}\n`,
|
||||
);
|
||||
const result = spawnSync(
|
||||
"corepack",
|
||||
[
|
||||
"pnpm",
|
||||
"install",
|
||||
"--frozen-lockfile",
|
||||
"--lockfile-only",
|
||||
"--ignore-scripts",
|
||||
],
|
||||
{
|
||||
cwd: fixtureRoot,
|
||||
encoding: "utf8",
|
||||
},
|
||||
);
|
||||
if (result.status === 0) {
|
||||
process.stderr.write("Tampered manifest unexpectedly passed frozen install.\n");
|
||||
process.exitCode = 1;
|
||||
} else {
|
||||
process.stdout.write("Frozen lockfile mismatch fixture: rejected PASS\n");
|
||||
}
|
||||
} finally {
|
||||
await rm(fixtureRoot, { recursive: true, force: true });
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
import { mkdir, readFile, readdir } from "node:fs/promises";
|
||||
|
||||
import { i18nReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import path from "node:path";
|
||||
|
||||
import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/i18n/catalog.ts";
|
||||
|
||||
const fixtureMode = process.argv.includes("--fixture");
|
||||
const failures: string[] = [];
|
||||
const sourceExtensions = /\.(?:ts|tsx|mts|cts)$/;
|
||||
const koreanLiteral = /[가-힣]/;
|
||||
const rawFailureRender =
|
||||
/(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
|
||||
|
||||
async function listSourceFiles(directory: string): Promise<string[]> {
|
||||
const result: string[] = [];
|
||||
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
||||
const target = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
|
||||
else if (sourceExtensions.test(entry.name)) result.push(target);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function placeholders(template: string): string[] {
|
||||
return [...template.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
|
||||
.map((match) => match[1])
|
||||
.sort();
|
||||
}
|
||||
|
||||
if (!fixtureMode) {
|
||||
const canonicalKeys = Object.keys(KO_MESSAGES).sort();
|
||||
for (const [locale, catalog] of Object.entries(MESSAGE_CATALOGS)) {
|
||||
const readableCatalog = catalog as Readonly<Record<string, string>>;
|
||||
const canonicalCatalog = KO_MESSAGES as Readonly<Record<string, string>>;
|
||||
const keys = Object.keys(catalog).sort();
|
||||
if (JSON.stringify(keys) !== JSON.stringify(canonicalKeys)) {
|
||||
failures.push(`${locale} catalog keys do not match ko-KR`);
|
||||
}
|
||||
for (const key of canonicalKeys) {
|
||||
if (
|
||||
JSON.stringify(placeholders(readableCatalog[key] ?? "")) !==
|
||||
JSON.stringify(placeholders(canonicalCatalog[key] ?? ""))
|
||||
) {
|
||||
failures.push(`${locale}:${key} interpolation parameters do not match`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (Object.keys(EN_MESSAGES).length !== canonicalKeys.length) {
|
||||
failures.push("en-US catalog key count does not match ko-KR");
|
||||
}
|
||||
}
|
||||
|
||||
const commonDirectories = [
|
||||
"src/presentation/boundaries",
|
||||
"src/presentation/components",
|
||||
"src/presentation/design-system",
|
||||
"src/presentation/forms",
|
||||
"src/presentation/layouts",
|
||||
"src/presentation/routes",
|
||||
"src/presentation/templates",
|
||||
];
|
||||
const sources = fixtureMode
|
||||
? await listSourceFiles("tests/fixtures/i18n/forbidden")
|
||||
: (
|
||||
await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
|
||||
).flat();
|
||||
|
||||
for (const file of sources) {
|
||||
const source = await readFile(file, "utf8");
|
||||
if (koreanLiteral.test(source)) {
|
||||
failures.push(`hardcoded common user-facing locale literal in ${file}`);
|
||||
}
|
||||
if (rawFailureRender.test(source)) {
|
||||
failures.push(`raw backend/error message rendered in ${file}`);
|
||||
}
|
||||
if (source.includes("dangerouslySetInnerHTML")) {
|
||||
failures.push(`untrusted HTML interpolation boundary in ${file}`);
|
||||
}
|
||||
}
|
||||
|
||||
const report = i18nReportArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
mode: fixtureMode ? "negative-fixture" : "source",
|
||||
localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
|
||||
messageKeyCount: Object.keys(KO_MESSAGES).length,
|
||||
checkedFiles: sources.length,
|
||||
failures,
|
||||
passed: failures.length === 0,
|
||||
});
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: fixtureMode
|
||||
? "artifacts/quality/i18n-fixture.json"
|
||||
: "artifacts/quality/i18n.json",
|
||||
schema: i18nReportArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`I18n contract: ${report.messageKeyCount} keys across ${report.localeCount} locales PASS\n`,
|
||||
);
|
||||
@@ -0,0 +1,204 @@
|
||||
import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
|
||||
|
||||
import { measureOptionalRecipeBundle } from "./lib/optional-recipe-bundle.ts";
|
||||
import { optionalRecipeFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
scanOptionalRecipeSources,
|
||||
scanProductionBundle,
|
||||
validateRecipeCatalog,
|
||||
} from "./lib/optional-recipes.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type ReferenceRuntimeRecipe = Readonly<{
|
||||
id: string;
|
||||
referenceRuntime: Readonly<{
|
||||
sourceRoots: readonly string[];
|
||||
}>;
|
||||
}>;
|
||||
|
||||
const catalog = JSON.parse(
|
||||
await readFile("config/recipes/frontend-capability-recipes.json", "utf8"),
|
||||
);
|
||||
const packageDocument = JSON.parse(await readFile("package.json", "utf8"));
|
||||
const catalogRecipes: unknown[] = Array.isArray(catalog.recipes)
|
||||
? (catalog.recipes as unknown[])
|
||||
: [];
|
||||
const referenceRuntimeRecipes = catalogRecipes.filter(
|
||||
(recipe: unknown): recipe is ReferenceRuntimeRecipe =>
|
||||
Boolean(
|
||||
recipe &&
|
||||
typeof recipe === "object" &&
|
||||
typeof (recipe as Record<string, unknown>).id === "string" &&
|
||||
(recipe as Record<string, unknown>).referenceRuntime &&
|
||||
typeof (recipe as Record<string, unknown>).referenceRuntime ===
|
||||
"object" &&
|
||||
Array.isArray(
|
||||
(
|
||||
(recipe as Record<string, unknown>)
|
||||
.referenceRuntime as Record<string, unknown>
|
||||
).sourceRoots,
|
||||
),
|
||||
),
|
||||
);
|
||||
const bundleBudgetFixtures = await Promise.all(
|
||||
referenceRuntimeRecipes.map(async (recipe) => {
|
||||
const measurement = await measureOptionalRecipeBundle({
|
||||
recipeId: recipe.id,
|
||||
sourceRoots: recipe.referenceRuntime.sourceRoots,
|
||||
bundleBudgetGzipBytes: 1,
|
||||
});
|
||||
return Object.freeze({
|
||||
recipeId: recipe.id,
|
||||
gzipBytes: measurement.gzipBytes,
|
||||
fixtureBudgetGzipBytes: measurement.bundleBudgetGzipBytes,
|
||||
rejected: !measurement.passed,
|
||||
});
|
||||
}),
|
||||
);
|
||||
|
||||
const cleanupCatalog = structuredClone(catalog);
|
||||
cleanupCatalog.recipes.find(
|
||||
(recipe: { id: string }) => recipe.id === "realtime",
|
||||
).lifecycleMethods = [];
|
||||
|
||||
const dependencyCatalog = structuredClone(catalog);
|
||||
dependencyCatalog.productionRuntimeDependencies = ["zustand"];
|
||||
|
||||
const workflowCatalog = structuredClone(catalog);
|
||||
workflowCatalog.recipes.find(
|
||||
(recipe: { id: string }) => recipe.id === "client-workflow",
|
||||
).serverStatePolicy = "copied-server-state";
|
||||
|
||||
const sourceViolations = await scanOptionalRecipeSources(
|
||||
"tests/fixtures/optional-recipes/forbidden",
|
||||
{ scanProductionBoundary: false },
|
||||
);
|
||||
const productionViolations = await scanOptionalRecipeSources(
|
||||
"tests/fixtures/optional-recipes/forbidden/production-import",
|
||||
{ scanProductionBoundary: true },
|
||||
);
|
||||
const runtimeCompositionViolations = await scanOptionalRecipeSources(
|
||||
"tests/fixtures/optional-recipes/forbidden/runtime-composition",
|
||||
{ scanProductionBoundary: true },
|
||||
);
|
||||
const bundleFixtureRoot = ".tmp/optional-recipe-runtime-bundle";
|
||||
await rm(bundleFixtureRoot, { recursive: true, force: true });
|
||||
await mkdir(`${bundleFixtureRoot}/assets`, { recursive: true });
|
||||
await writeFile(
|
||||
`${bundleFixtureRoot}/assets/runtime.js`,
|
||||
'throw new TypeError("OPFS runtime policy is invalid.");\n',
|
||||
);
|
||||
const bundleViolations = await scanProductionBundle(bundleFixtureRoot);
|
||||
await rm(bundleFixtureRoot, { recursive: true, force: true });
|
||||
const inventoryFixtureRoot =
|
||||
".tmp/optional-recipe-runtime-module-inventory";
|
||||
await rm(inventoryFixtureRoot, { recursive: true, force: true });
|
||||
await mkdir(`${inventoryFixtureRoot}/.vite`, { recursive: true });
|
||||
await writeFile(`${inventoryFixtureRoot}/.vite/manifest.json`, "{}\n");
|
||||
await writeFile(
|
||||
`${inventoryFixtureRoot}/.vite/module-inventory.json`,
|
||||
`${JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
chunks: [
|
||||
{
|
||||
fileName: "assets/application.js",
|
||||
modules: [
|
||||
"src/adapters/browser-files/browser-file-vault.ts",
|
||||
],
|
||||
},
|
||||
],
|
||||
})}\n`,
|
||||
);
|
||||
const inventoryViolations =
|
||||
await scanProductionBundle(inventoryFixtureRoot);
|
||||
await rm(inventoryFixtureRoot, { recursive: true, force: true });
|
||||
sourceViolations.push(...productionViolations);
|
||||
sourceViolations.push(...runtimeCompositionViolations);
|
||||
const ruleIds = new Set(sourceViolations.map(({ ruleId }) => ruleId));
|
||||
const results = [
|
||||
{
|
||||
id: "cleanup-omission",
|
||||
passed: validateRecipeCatalog(cleanupCatalog, packageDocument).some(
|
||||
(violation) => violation === "realtime:CLEANUP_CONTRACT_MISSING",
|
||||
),
|
||||
},
|
||||
{
|
||||
id: "unselected-runtime-dependency",
|
||||
passed: validateRecipeCatalog(dependencyCatalog, packageDocument).includes(
|
||||
"UNSELECTED_RUNTIME_DEPENDENCY",
|
||||
),
|
||||
},
|
||||
{
|
||||
id: "server-state-policy",
|
||||
passed: validateRecipeCatalog(workflowCatalog, packageDocument).includes(
|
||||
"client-workflow:SERVER_STATE_DUPLICATION_POLICY",
|
||||
),
|
||||
},
|
||||
{
|
||||
id: "vendor-direct-import",
|
||||
passed: ruleIds.has("VENDOR_IMPORT_OUTSIDE_ADAPTER"),
|
||||
},
|
||||
{
|
||||
id: "credential-leak",
|
||||
passed: ruleIds.has("CREDENTIAL_LEAK_PATH"),
|
||||
},
|
||||
{
|
||||
id: "server-state-source-duplication",
|
||||
passed: ruleIds.has("CLIENT_STORE_DUPLICATES_SERVER_STATE"),
|
||||
},
|
||||
{
|
||||
id: "production-imports-recipe",
|
||||
passed: ruleIds.has("PRODUCTION_IMPORTS_RECIPE"),
|
||||
},
|
||||
{
|
||||
id: "reference-runtime-not-composed",
|
||||
passed: ruleIds.has("REFERENCE_RUNTIME_COMPOSED_WITHOUT_SELECTION"),
|
||||
},
|
||||
{
|
||||
id: "reference-runtime-not-bundled",
|
||||
passed: bundleViolations.some((file) => file.endsWith("runtime.js")),
|
||||
},
|
||||
{
|
||||
id: "reference-runtime-module-not-bundled",
|
||||
passed: inventoryViolations.some((violation) =>
|
||||
violation.includes(
|
||||
"src/adapters/browser-files/browser-file-vault.ts",
|
||||
),
|
||||
),
|
||||
},
|
||||
{
|
||||
id: "reference-runtime-bundle-over-budget",
|
||||
passed:
|
||||
bundleBudgetFixtures.length === referenceRuntimeRecipes.length &&
|
||||
bundleBudgetFixtures.length > 0 &&
|
||||
bundleBudgetFixtures.every(
|
||||
(fixture) =>
|
||||
fixture.gzipBytes > fixture.fixtureBudgetGzipBytes &&
|
||||
fixture.rejected,
|
||||
),
|
||||
},
|
||||
];
|
||||
const report = optionalRecipeFixturesArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
results,
|
||||
bundleBudgetFixtures,
|
||||
passed: results.every(({ passed }) => passed),
|
||||
});
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/quality/optional-recipe-fixtures.json",
|
||||
schema: optionalRecipeFixturesArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
if (!report.passed) {
|
||||
process.stderr.write(
|
||||
`Optional recipe negative fixtures failed: ${results
|
||||
.filter(({ passed }) => !passed)
|
||||
.map(({ id }) => id)
|
||||
.join(", ")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Optional recipe negative fixtures: PASS (${results.length} forbidden cases rejected)\n`,
|
||||
);
|
||||
@@ -0,0 +1,62 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { readdir } from "node:fs/promises";
|
||||
import { extname, resolve } from "node:path";
|
||||
|
||||
const recipeRoot = resolve("recipes");
|
||||
const pnpmCli = requireEnvironment("npm_execpath");
|
||||
|
||||
if (!(await containsTypeScriptSource(recipeRoot))) {
|
||||
process.stdout.write(
|
||||
"Optional recipe typecheck: SKIP (no recipe TypeScript sources installed)\n",
|
||||
);
|
||||
} else {
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[pnpmCli, "exec", "tsc", "--project", "tsconfig.recipes.json"],
|
||||
{ stdio: "inherit" },
|
||||
);
|
||||
if (result.error) {
|
||||
throw result.error;
|
||||
}
|
||||
process.exitCode = result.status ?? 1;
|
||||
}
|
||||
|
||||
function requireEnvironment(name: string): string {
|
||||
const value = process.env[name];
|
||||
if (!value) {
|
||||
throw new Error(`${name} is required to typecheck optional recipes`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
async function containsTypeScriptSource(directory: string): Promise<boolean> {
|
||||
let entries;
|
||||
try {
|
||||
entries = await readdir(directory, { withFileTypes: true });
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) {
|
||||
return false;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
|
||||
for (const entry of entries) {
|
||||
const target = resolve(directory, entry.name);
|
||||
if (entry.isDirectory() && (await containsTypeScriptSource(target))) {
|
||||
return true;
|
||||
}
|
||||
if (entry.isFile() && [".ts", ".tsx", ".mts", ".cts"].includes(extname(entry.name))) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
"code" in error &&
|
||||
error.code === code
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,271 @@
|
||||
import { mkdir, readFile, stat } from "node:fs/promises";
|
||||
|
||||
import { optionalRecipesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
measureOptionalRecipeBundle,
|
||||
type OptionalRecipeBundleMeasurement,
|
||||
} from "./lib/optional-recipe-bundle.ts";
|
||||
import {
|
||||
scanOptionalRecipeSources,
|
||||
scanProductionBundle,
|
||||
validateRecipeCatalog,
|
||||
} from "./lib/optional-recipes.ts";
|
||||
import { assertMatchesJsonSchema } from "./lib/json-schema.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type GateViolation = Readonly<{
|
||||
ruleId: string;
|
||||
path: string;
|
||||
detail?: string;
|
||||
}>;
|
||||
|
||||
type ReferenceRuntimeBundleInput = Readonly<{
|
||||
recipeId: string;
|
||||
sourceRoots: readonly string[];
|
||||
bundleBudgetGzipBytes: number;
|
||||
}>;
|
||||
|
||||
const argument = (name: string, fallback: string): string => {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index === -1 ? fallback : (process.argv[index + 1] ?? fallback);
|
||||
};
|
||||
|
||||
const catalogPath = argument(
|
||||
"--catalog",
|
||||
"config/recipes/frontend-capability-recipes.json",
|
||||
);
|
||||
const sourceRoot = argument("--source-root", "src");
|
||||
const distRoot = argument("--dist-root", "dist");
|
||||
const artifactPath = argument(
|
||||
"--artifact",
|
||||
"artifacts/quality/optional-recipes.json",
|
||||
);
|
||||
const requireDist = process.argv.includes("--require-dist");
|
||||
|
||||
const catalog = JSON.parse(
|
||||
await readFile(catalogPath, "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
const recipes = Array.isArray(catalog.recipes) ? catalog.recipes : [];
|
||||
const packageDocument = JSON.parse(
|
||||
await readFile("package.json", "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
const catalogSchemaViolations: string[] = [];
|
||||
try {
|
||||
assertMatchesJsonSchema(
|
||||
JSON.parse(
|
||||
await readFile(
|
||||
"schemas/config/frontend-capability-recipes.schema.json",
|
||||
"utf8",
|
||||
),
|
||||
),
|
||||
catalog,
|
||||
"optional recipe catalog",
|
||||
);
|
||||
} catch {
|
||||
catalogSchemaViolations.push("CATALOG_JSON_SCHEMA_INVALID");
|
||||
}
|
||||
const catalogViolations = [
|
||||
...catalogSchemaViolations,
|
||||
...validateRecipeCatalog(catalog, packageDocument),
|
||||
];
|
||||
const runtimeSourceViolations = (
|
||||
await Promise.all(
|
||||
recipes.flatMap((recipe: unknown) => {
|
||||
if (!recipe || typeof recipe !== "object") return [];
|
||||
const row = recipe as Record<string, unknown>;
|
||||
const runtime = row.referenceRuntime;
|
||||
if (!runtime || typeof runtime !== "object") return [];
|
||||
const sourceRoots = (runtime as Record<string, unknown>).sourceRoots;
|
||||
if (!Array.isArray(sourceRoots)) return [];
|
||||
return sourceRoots
|
||||
.filter(
|
||||
(sourceRoot): sourceRoot is string =>
|
||||
typeof sourceRoot === "string",
|
||||
)
|
||||
.map(async (sourceRoot) => ({
|
||||
sourceRoot,
|
||||
exists: await stat(sourceRoot)
|
||||
.then(() => true)
|
||||
.catch(() => false),
|
||||
}));
|
||||
}),
|
||||
)
|
||||
).filter(({ exists }) => !exists);
|
||||
const {
|
||||
inputs: referenceRuntimeBundleInputs,
|
||||
violations: referenceRuntimeBundleConfigurationViolations,
|
||||
} = referenceRuntimeBundleInputsFrom(recipes);
|
||||
const referenceRuntimeBundles: OptionalRecipeBundleMeasurement[] = [];
|
||||
const referenceRuntimeBundleMeasurementViolations: GateViolation[] = [];
|
||||
for (const bundleInput of referenceRuntimeBundleInputs) {
|
||||
try {
|
||||
const measurement = await measureOptionalRecipeBundle(bundleInput);
|
||||
referenceRuntimeBundles.push(measurement);
|
||||
if (!measurement.passed) {
|
||||
referenceRuntimeBundleMeasurementViolations.push({
|
||||
ruleId: "REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED",
|
||||
path: measurement.recipeId,
|
||||
detail:
|
||||
`${measurement.gzipBytes} > ` +
|
||||
`${measurement.bundleBudgetGzipBytes} gzip bytes`,
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
referenceRuntimeBundleMeasurementViolations.push({
|
||||
ruleId: "REFERENCE_RUNTIME_BUNDLE_MEASUREMENT_FAILED",
|
||||
path: bundleInput.recipeId,
|
||||
detail: safeErrorSummary(error),
|
||||
});
|
||||
}
|
||||
}
|
||||
referenceRuntimeBundles.sort((left, right) =>
|
||||
compareText(left.recipeId, right.recipeId),
|
||||
);
|
||||
const sourceViolations = await scanOptionalRecipeSources(sourceRoot);
|
||||
const bundlePresent = await stat(`${distRoot}/.vite/manifest.json`)
|
||||
.then(() => true)
|
||||
.catch(() => false);
|
||||
const bundleViolations = await scanProductionBundle(distRoot);
|
||||
const violations: GateViolation[] = [
|
||||
...catalogViolations.map((ruleId) => ({ ruleId, path: catalogPath })),
|
||||
...runtimeSourceViolations.map(({ sourceRoot }) => ({
|
||||
ruleId: "REFERENCE_RUNTIME_SOURCE_MISSING",
|
||||
path: sourceRoot,
|
||||
})),
|
||||
...sourceViolations,
|
||||
...bundleViolations.map((path) => ({
|
||||
ruleId: "UNSELECTED_RECIPE_IN_PRODUCTION_BUNDLE",
|
||||
path,
|
||||
})),
|
||||
...(requireDist && !bundlePresent
|
||||
? [{ ruleId: "PRODUCTION_BUNDLE_MISSING", path: distRoot }]
|
||||
: []),
|
||||
...referenceRuntimeBundleConfigurationViolations,
|
||||
...referenceRuntimeBundleMeasurementViolations,
|
||||
];
|
||||
const report = optionalRecipesArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
decisionId: "VD-10",
|
||||
selectedCapabilities: [],
|
||||
referenceRuntimes: recipes
|
||||
.filter(
|
||||
(recipe: unknown): recipe is Record<string, unknown> =>
|
||||
Boolean(
|
||||
recipe &&
|
||||
typeof recipe === "object" &&
|
||||
(recipe as Record<string, unknown>).referenceRuntime,
|
||||
),
|
||||
)
|
||||
.map((recipe: Record<string, unknown>) => ({
|
||||
id: recipe.id,
|
||||
referenceRuntime: recipe.referenceRuntime,
|
||||
})),
|
||||
recipeCount: recipes.length,
|
||||
productionRuntimeDependencies:
|
||||
catalog.productionRuntimeDependencies ?? null,
|
||||
referenceRuntimeBundleBudgets: referenceRuntimeBundles,
|
||||
bundleStatus: bundlePresent
|
||||
? bundleViolations.length === 0
|
||||
? "PASS"
|
||||
: "FAIL"
|
||||
: "NOT_BUILT",
|
||||
violations,
|
||||
passed: violations.length === 0,
|
||||
});
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: artifactPath,
|
||||
schema: optionalRecipesArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
|
||||
if (violations.length > 0) {
|
||||
process.stderr.write(
|
||||
`Optional recipe contract failed:\n${violations
|
||||
.map(
|
||||
(violation) =>
|
||||
`${violation.ruleId}: ${violation.path}` +
|
||||
(violation.detail ? ` (${violation.detail})` : ""),
|
||||
)
|
||||
.join("\n")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
const referenceRuntimeBudgetStatus =
|
||||
referenceRuntimeBundles.length > 0
|
||||
? `, budgets=${referenceRuntimeBundles
|
||||
.map(
|
||||
(measurement) =>
|
||||
`${measurement.recipeId}:${measurement.gzipBytes}/` +
|
||||
measurement.bundleBudgetGzipBytes,
|
||||
)
|
||||
.join(",")} gzip bytes`
|
||||
: "";
|
||||
process.stdout.write(
|
||||
`Optional recipes: PASS (${report.recipeCount} optional capabilities, ${report.referenceRuntimes.length} uncomposed reference runtimes, bundle=${report.bundleStatus}${referenceRuntimeBudgetStatus})\n`,
|
||||
);
|
||||
|
||||
function referenceRuntimeBundleInputsFrom(
|
||||
recipeRows: readonly unknown[],
|
||||
): Readonly<{
|
||||
inputs: readonly ReferenceRuntimeBundleInput[];
|
||||
violations: readonly GateViolation[];
|
||||
}> {
|
||||
const inputs: ReferenceRuntimeBundleInput[] = [];
|
||||
const violations: GateViolation[] = [];
|
||||
for (const recipe of recipeRows) {
|
||||
if (!recipe || typeof recipe !== "object") continue;
|
||||
const row = recipe as Record<string, unknown>;
|
||||
if (row.referenceRuntime === undefined) continue;
|
||||
const recipeId =
|
||||
typeof row.id === "string" ? row.id : "unknown-reference-runtime";
|
||||
const runtime = row.referenceRuntime;
|
||||
const sourceRoots =
|
||||
runtime && typeof runtime === "object"
|
||||
? (runtime as Record<string, unknown>).sourceRoots
|
||||
: null;
|
||||
if (
|
||||
!Array.isArray(sourceRoots) ||
|
||||
!sourceRoots.every(
|
||||
(sourceRoot): sourceRoot is string =>
|
||||
typeof sourceRoot === "string",
|
||||
) ||
|
||||
!Number.isSafeInteger(row.bundleBudgetGzipBytes) ||
|
||||
(row.bundleBudgetGzipBytes as number) < 1
|
||||
) {
|
||||
violations.push({
|
||||
ruleId: "REFERENCE_RUNTIME_BUNDLE_CONFIGURATION_INVALID",
|
||||
path: recipeId,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
inputs.push(
|
||||
Object.freeze({
|
||||
recipeId,
|
||||
sourceRoots: Object.freeze([...sourceRoots]),
|
||||
bundleBudgetGzipBytes: row.bundleBudgetGzipBytes as number,
|
||||
}),
|
||||
);
|
||||
}
|
||||
return Object.freeze({
|
||||
inputs: Object.freeze(
|
||||
inputs.sort((left, right) =>
|
||||
compareText(left.recipeId, right.recipeId),
|
||||
),
|
||||
),
|
||||
violations: Object.freeze(violations),
|
||||
});
|
||||
}
|
||||
|
||||
function safeErrorSummary(error: unknown): string {
|
||||
const message =
|
||||
error instanceof Error ? error.message : "unknown measurement failure";
|
||||
return message
|
||||
.split(/\r?\n/, 1)[0]
|
||||
?.replaceAll(process.cwd(), ".")
|
||||
.slice(0, 512) ?? "unknown measurement failure";
|
||||
}
|
||||
|
||||
function compareText(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
import { mkdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { realtimeBoundariesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { scanRealtimeBoundaries } from "./lib/realtime-boundaries.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const sourceRoot = argument("--source-root") ?? "src";
|
||||
const artifact =
|
||||
argument("--artifact") ??
|
||||
"artifacts/quality/realtime-boundaries.json";
|
||||
const violations = await scanRealtimeBoundaries(sourceRoot);
|
||||
const report = realtimeBoundariesArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
sourceRoot,
|
||||
violations,
|
||||
passed: violations.length === 0,
|
||||
});
|
||||
|
||||
await mkdir(path.dirname(artifact), { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: artifact,
|
||||
schema: realtimeBoundariesArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
|
||||
if (violations.length > 0) {
|
||||
for (const violation of violations) {
|
||||
process.stderr.write(
|
||||
`${violation.file}:${violation.line} ${violation.ruleId}\n`,
|
||||
);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`Realtime boundaries: PASS (${sourceRoot})\n`,
|
||||
);
|
||||
|
||||
function argument(name: string): string | undefined {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 ? process.argv[index + 1] : undefined;
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
const checker = "scripts/check-realtime-boundaries.ts";
|
||||
const allowed = run(
|
||||
"tests/fixtures/realtime-boundaries/allowed",
|
||||
".tmp/realtime-boundaries-allowed.json",
|
||||
);
|
||||
const forbidden = run(
|
||||
"tests/fixtures/realtime-boundaries/forbidden",
|
||||
".tmp/realtime-boundaries-forbidden.json",
|
||||
);
|
||||
const forbiddenOutput = `${forbidden.stdout}${forbidden.stderr}`;
|
||||
const expectedRules = [
|
||||
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
|
||||
"PRESENTATION_INTERVAL_OWNER",
|
||||
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
|
||||
] as const;
|
||||
|
||||
if (
|
||||
allowed.status !== 0 ||
|
||||
forbidden.status === 0 ||
|
||||
!expectedRules.every((rule) => forbiddenOutput.includes(rule))
|
||||
) {
|
||||
process.stderr.write(allowed.stdout);
|
||||
process.stderr.write(allowed.stderr);
|
||||
process.stderr.write(forbidden.stdout);
|
||||
process.stderr.write(forbidden.stderr);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`Realtime boundary fixtures: PASS (${expectedRules.length} forbidden rules rejected)\n`,
|
||||
);
|
||||
|
||||
function run(sourceRoot: string, artifact: string) {
|
||||
return spawnSync(
|
||||
process.execPath,
|
||||
[
|
||||
checker,
|
||||
"--source-root",
|
||||
sourceRoot,
|
||||
"--artifact",
|
||||
artifact,
|
||||
],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,697 @@
|
||||
import {
|
||||
access,
|
||||
mkdir,
|
||||
readFile,
|
||||
readdir,
|
||||
} from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import {
|
||||
canonicalizeRegistryValue,
|
||||
diffRegistrySnapshots,
|
||||
registrySnapshotDigest,
|
||||
validateBreakingEvidence,
|
||||
verifyRegistryBaselineApproval,
|
||||
} from "./lib/registry-compatibility.ts";
|
||||
import { assertMatchesJsonSchema } from "./lib/json-schema.ts";
|
||||
import {
|
||||
registryGovernanceRunArtifactSchema,
|
||||
registrySnapshotArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type RegistryRow = Record<string, unknown>;
|
||||
type RegistryRows = Record<string, RegistryRow>;
|
||||
type RegistryReference = Readonly<{
|
||||
registryId: string;
|
||||
field: string;
|
||||
targetField: string;
|
||||
}>;
|
||||
type RegistryConsumer = Readonly<{ path: string; token: string }>;
|
||||
type RegistrySnapshotProjection = Readonly<{
|
||||
singletonRowKey: string;
|
||||
canonicalArrayKeyFields: Readonly<Record<string, readonly string[]>>;
|
||||
}>;
|
||||
type RegistrySpecification = Readonly<{
|
||||
registryId: string;
|
||||
owner: string;
|
||||
path: string;
|
||||
exportName: string;
|
||||
declaredRows?: unknown;
|
||||
rowsPath?: string;
|
||||
rowKeyFields?: readonly string[];
|
||||
requiredFields: readonly string[];
|
||||
fieldTypes?: Readonly<Record<string, string>>;
|
||||
keyField?: string;
|
||||
uniqueFields?: readonly string[];
|
||||
uniqueFieldSets?: readonly (readonly string[])[];
|
||||
snapshotProjection?: RegistrySnapshotProjection;
|
||||
allowedValues?: Readonly<Record<string, readonly unknown[]>>;
|
||||
references?: readonly RegistryReference[];
|
||||
breakingFields?: readonly string[];
|
||||
consumers?: readonly RegistryConsumer[];
|
||||
consumerIdentityField?: string;
|
||||
consumerDirectories?: readonly string[];
|
||||
orphanExemptRows?: readonly string[];
|
||||
}>;
|
||||
type RegistryGovernance = Readonly<{
|
||||
registries: readonly RegistrySpecification[];
|
||||
sourceDirectories?: readonly string[];
|
||||
}>;
|
||||
type RegistrySnapshot = Record<string, unknown>;
|
||||
type CompatibilitySummary = Readonly<{
|
||||
impact: string;
|
||||
changes: readonly unknown[];
|
||||
}>;
|
||||
|
||||
function argumentValue(
|
||||
name: string,
|
||||
fallback: string | undefined,
|
||||
): string | undefined {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 && process.argv[index + 1]
|
||||
? process.argv[index + 1]
|
||||
: fallback;
|
||||
}
|
||||
|
||||
const defaultGovernancePath = "config/contracts/registry-governance.json";
|
||||
const governancePath =
|
||||
argumentValue("--governance", defaultGovernancePath) ??
|
||||
defaultGovernancePath;
|
||||
const artifactPath =
|
||||
argumentValue("--artifact", "artifacts/quality/registries.json") ??
|
||||
"artifacts/quality/registries.json";
|
||||
const usesRepositoryGovernance = governancePath === defaultGovernancePath;
|
||||
const usesRepositoryBaseline =
|
||||
usesRepositoryGovernance &&
|
||||
!process.argv.includes("--no-baseline");
|
||||
const baselinePath = argumentValue(
|
||||
"--baseline",
|
||||
usesRepositoryBaseline
|
||||
? "config/contracts/registry-baseline.json"
|
||||
: undefined,
|
||||
);
|
||||
const approvalPath = argumentValue(
|
||||
"--approval",
|
||||
usesRepositoryBaseline
|
||||
? "config/contracts/registry-baseline.approval.json"
|
||||
: undefined,
|
||||
);
|
||||
const evidencePath = argumentValue(
|
||||
"--compatibility-evidence",
|
||||
usesRepositoryBaseline
|
||||
? "config/contracts/registry-change-evidence.json"
|
||||
: undefined,
|
||||
);
|
||||
const governance = JSON.parse(
|
||||
await readFile(governancePath, "utf8"),
|
||||
) as RegistryGovernance;
|
||||
const failures: string[] = [];
|
||||
const owners = new Map<string, string>();
|
||||
const snapshots: RegistrySnapshot[] = [];
|
||||
const rowsByRegistry = new Map<string, RegistryRows>();
|
||||
const sourcesByRegistry = new Map<string, string>();
|
||||
const registryExtensions = [".ts", ".tsx", ".mts", ".cts"];
|
||||
|
||||
async function resolveRegistrySource(
|
||||
declaredPath: string,
|
||||
): Promise<string | null> {
|
||||
const extension = path.extname(declaredPath);
|
||||
const basePath = extension
|
||||
? declaredPath.slice(0, -extension.length)
|
||||
: declaredPath;
|
||||
const candidates: string[] = [];
|
||||
for (const candidateExtension of registryExtensions) {
|
||||
const candidate = `${basePath}${candidateExtension}`;
|
||||
try {
|
||||
await access(candidate);
|
||||
candidates.push(candidate);
|
||||
} catch {
|
||||
// Continue through the supported TypeScript source extensions.
|
||||
}
|
||||
}
|
||||
if (candidates.length > 1) {
|
||||
failures.push(
|
||||
`ambiguous registry source ${declaredPath}: ${candidates.join(", ")}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
return candidates[0] ?? null;
|
||||
}
|
||||
|
||||
function runtimeType(value: unknown): string {
|
||||
if (value === null) return "null";
|
||||
if (Array.isArray(value)) return "array";
|
||||
if (Number.isInteger(value)) return "integer";
|
||||
return typeof value;
|
||||
}
|
||||
|
||||
function matchesDeclaredType(value: unknown, declaration: string): boolean {
|
||||
const actual = runtimeType(value);
|
||||
return declaration
|
||||
.split("|")
|
||||
.some(
|
||||
(candidate) =>
|
||||
candidate === actual ||
|
||||
(candidate === "number" && actual === "integer"),
|
||||
);
|
||||
}
|
||||
|
||||
type FieldLookup = Readonly<{
|
||||
found: boolean;
|
||||
value: unknown;
|
||||
}>;
|
||||
|
||||
function lookupField(value: unknown, fieldPath: string): FieldLookup {
|
||||
let current = value;
|
||||
for (const segment of fieldPath.split(".")) {
|
||||
if (
|
||||
!current ||
|
||||
typeof current !== "object" ||
|
||||
Array.isArray(current) ||
|
||||
!Object.hasOwn(current, segment)
|
||||
) {
|
||||
return Object.freeze({ found: false, value: undefined });
|
||||
}
|
||||
current = (current as Record<string, unknown>)[segment];
|
||||
}
|
||||
return Object.freeze({ found: true, value: current });
|
||||
}
|
||||
|
||||
function projectRegistryRows(
|
||||
specification: RegistrySpecification,
|
||||
exportedValue: unknown,
|
||||
): RegistryRows | null {
|
||||
const selected = specification.rowsPath
|
||||
? lookupField(exportedValue, specification.rowsPath)
|
||||
: Object.freeze({ found: true, value: exportedValue });
|
||||
if (!selected.found) {
|
||||
failures.push(
|
||||
`${specification.registryId} is missing rows path ${specification.rowsPath}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
if (!Array.isArray(selected.value)) {
|
||||
if (
|
||||
!selected.value ||
|
||||
typeof selected.value !== "object"
|
||||
) {
|
||||
failures.push(`${specification.registryId} is not an object registry`);
|
||||
return null;
|
||||
}
|
||||
return selected.value as RegistryRows;
|
||||
}
|
||||
|
||||
const projected: RegistryRows = {};
|
||||
const keyOccurrences = new Map<string, number>();
|
||||
for (const [index, row] of selected.value.entries()) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) {
|
||||
projected[String(index)] = row as RegistryRow;
|
||||
continue;
|
||||
}
|
||||
const keyValues = (specification.rowKeyFields ?? []).map(
|
||||
(field) => lookupField(row, field).value,
|
||||
);
|
||||
const baseKey =
|
||||
keyValues.length > 0
|
||||
? JSON.stringify(keyValues.map(canonicalizeRegistryValue))
|
||||
: String(index);
|
||||
const occurrence = keyOccurrences.get(baseKey) ?? 0;
|
||||
keyOccurrences.set(baseKey, occurrence + 1);
|
||||
projected[occurrence === 0 ? baseKey : `${baseKey}#${occurrence + 1}`] =
|
||||
row as RegistryRow;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function snapshotKeyField(
|
||||
value: unknown,
|
||||
fieldPath: string,
|
||||
): FieldLookup {
|
||||
return fieldPath === "$value"
|
||||
? Object.freeze({ found: true, value })
|
||||
: lookupField(value, fieldPath);
|
||||
}
|
||||
|
||||
function replaceProjectedField(
|
||||
row: RegistryRow,
|
||||
fieldPath: string,
|
||||
value: unknown,
|
||||
): boolean {
|
||||
const segments = fieldPath.split(".");
|
||||
const finalSegment = segments.pop();
|
||||
if (!finalSegment) return false;
|
||||
let current = row;
|
||||
for (const segment of segments) {
|
||||
const next = current[segment];
|
||||
if (!next || typeof next !== "object" || Array.isArray(next)) {
|
||||
return false;
|
||||
}
|
||||
current = next as RegistryRow;
|
||||
}
|
||||
current[finalSegment] = value;
|
||||
return true;
|
||||
}
|
||||
|
||||
function projectSnapshotRows(
|
||||
specification: RegistrySpecification,
|
||||
exportedValue: unknown,
|
||||
validatedRows: RegistryRows,
|
||||
): RegistryRows | null {
|
||||
const projection = specification.snapshotProjection;
|
||||
if (!projection) return validatedRows;
|
||||
if (
|
||||
!exportedValue ||
|
||||
typeof exportedValue !== "object" ||
|
||||
Array.isArray(exportedValue)
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId} snapshot projection requires an object export`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
|
||||
const canonicalRow = canonicalizeRegistryValue(exportedValue) as RegistryRow;
|
||||
for (const [fieldPath, keyFields] of Object.entries(
|
||||
projection.canonicalArrayKeyFields,
|
||||
)) {
|
||||
const selected = lookupField(exportedValue, fieldPath);
|
||||
if (!selected.found || !Array.isArray(selected.value)) {
|
||||
failures.push(
|
||||
`${specification.registryId} snapshot field ${fieldPath} must be an array`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
const keyedItems: Array<{ identity: string; value: unknown }> = [];
|
||||
const identities = new Set<string>();
|
||||
for (const [index, item] of selected.value.entries()) {
|
||||
const keyValues = keyFields.map((field) => snapshotKeyField(item, field));
|
||||
const missingIndex = keyValues.findIndex((field) => !field.found);
|
||||
if (missingIndex >= 0) {
|
||||
failures.push(
|
||||
`${specification.registryId} snapshot field ${fieldPath}[${index}] is missing key ${keyFields[missingIndex]}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
const identity = JSON.stringify(
|
||||
keyValues.map((field) => canonicalizeRegistryValue(field.value)),
|
||||
);
|
||||
if (identities.has(identity)) {
|
||||
failures.push(
|
||||
`${specification.registryId} snapshot field ${fieldPath} duplicates key ${identity}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
identities.add(identity);
|
||||
keyedItems.push({
|
||||
identity,
|
||||
value: canonicalizeRegistryValue(item),
|
||||
});
|
||||
}
|
||||
keyedItems.sort((left, right) =>
|
||||
left.identity.localeCompare(right.identity),
|
||||
);
|
||||
if (
|
||||
!replaceProjectedField(
|
||||
canonicalRow,
|
||||
fieldPath,
|
||||
keyedItems.map((item) => item.value),
|
||||
)
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId} snapshot field ${fieldPath} cannot be projected`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
[projection.singletonRowKey]: canonicalRow,
|
||||
});
|
||||
}
|
||||
|
||||
async function filesBelow(directory: string): Promise<string[]> {
|
||||
try {
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
const groups = await Promise.all(
|
||||
entries.map((entry) => {
|
||||
const target = path.join(directory, entry.name);
|
||||
return entry.isDirectory() ? filesBelow(target) : [target];
|
||||
}),
|
||||
);
|
||||
return groups.flat().filter((file) =>
|
||||
/\.(?:ts|tsx|mts|cts)$/.test(file),
|
||||
);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
for (const specification of governance.registries) {
|
||||
if (owners.has(specification.registryId)) {
|
||||
failures.push(`duplicate owner for ${specification.registryId}`);
|
||||
}
|
||||
owners.set(specification.registryId, specification.owner);
|
||||
|
||||
let rows = specification.declaredRows;
|
||||
const sourcePath = await resolveRegistrySource(specification.path);
|
||||
try {
|
||||
if (!sourcePath) throw new Error("missing registry source");
|
||||
const registryModule = (await import(
|
||||
`${pathToFileURL(path.resolve(sourcePath)).href}?registry-check=${Date.now()}`
|
||||
)) as Record<string, unknown>;
|
||||
rows = registryModule[specification.exportName];
|
||||
} catch {
|
||||
if (!rows) failures.push(`missing registry source ${specification.path}`);
|
||||
}
|
||||
|
||||
const registryRows = projectRegistryRows(specification, rows);
|
||||
if (!registryRows) {
|
||||
continue;
|
||||
}
|
||||
rowsByRegistry.set(specification.registryId, registryRows);
|
||||
sourcesByRegistry.set(
|
||||
specification.registryId,
|
||||
sourcePath ?? specification.path,
|
||||
);
|
||||
|
||||
for (const [rowName, row] of Object.entries(registryRows)) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) {
|
||||
failures.push(`${specification.registryId}.${rowName} is not an object`);
|
||||
continue;
|
||||
}
|
||||
for (const field of specification.requiredFields) {
|
||||
if (!lookupField(row, field).found) {
|
||||
failures.push(`${specification.registryId}.${rowName} missing ${field}`);
|
||||
}
|
||||
}
|
||||
for (const [field, declaredType] of Object.entries(
|
||||
specification.fieldTypes ?? {},
|
||||
)) {
|
||||
if (
|
||||
lookupField(row, field).found &&
|
||||
!matchesDeclaredType(
|
||||
lookupField(row, field).value,
|
||||
String(declaredType),
|
||||
)
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${runtimeType(lookupField(row, field).value)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (
|
||||
specification.keyField &&
|
||||
lookupField(row, specification.keyField).value !== rowName
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName}.${specification.keyField} must match its registry key`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const field of specification.uniqueFields ?? []) {
|
||||
const values = new Map<string, string>();
|
||||
for (const [rowName, row] of Object.entries(registryRows)) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) continue;
|
||||
const selected = lookupField(row, field);
|
||||
if (!selected.found) continue;
|
||||
const value = selected.value;
|
||||
const identity = JSON.stringify(canonicalizeRegistryValue(value));
|
||||
if (values.has(identity)) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName} duplicates ${field}=${String(value)} from ${values.get(identity)}`,
|
||||
);
|
||||
} else {
|
||||
values.set(identity, rowName);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const fields of specification.uniqueFieldSets ?? []) {
|
||||
const values = new Map<string, string>();
|
||||
for (const [rowName, row] of Object.entries(registryRows)) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) continue;
|
||||
const selected = fields.map((field) => lookupField(row, field));
|
||||
if (selected.some((field) => !field.found)) continue;
|
||||
const identity = JSON.stringify(
|
||||
selected.map((field) => canonicalizeRegistryValue(field.value)),
|
||||
);
|
||||
const previous = values.get(identity);
|
||||
if (previous) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName} duplicates ${fields.join("+")}=${identity} from ${previous}`,
|
||||
);
|
||||
} else {
|
||||
values.set(identity, rowName);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const [field, allowed] of Object.entries(
|
||||
specification.allowedValues ?? {},
|
||||
)) {
|
||||
for (const [rowName, row] of Object.entries(registryRows)) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) continue;
|
||||
if (
|
||||
!allowed.some((value) =>
|
||||
Object.is(value, lookupField(row, field).value),
|
||||
)
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName}.${field} has unknown value ${String(lookupField(row, field).value)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const contract = Object.freeze({
|
||||
requiredFields: specification.requiredFields,
|
||||
fieldTypes: specification.fieldTypes ?? {},
|
||||
uniqueFields: specification.uniqueFields ?? [],
|
||||
allowedValues: specification.allowedValues ?? {},
|
||||
references: specification.references ?? [],
|
||||
keyField: specification.keyField ?? null,
|
||||
breakingFields: specification.breakingFields ?? [],
|
||||
...(specification.rowsPath
|
||||
? { rowsPath: specification.rowsPath }
|
||||
: {}),
|
||||
...(specification.rowKeyFields
|
||||
? { rowKeyFields: specification.rowKeyFields }
|
||||
: {}),
|
||||
...(specification.uniqueFieldSets
|
||||
? { uniqueFieldSets: specification.uniqueFieldSets }
|
||||
: {}),
|
||||
...(specification.snapshotProjection
|
||||
? { snapshotProjection: specification.snapshotProjection }
|
||||
: {}),
|
||||
});
|
||||
const snapshotRows = projectSnapshotRows(specification, rows, registryRows);
|
||||
if (!snapshotRows) continue;
|
||||
snapshots.push({
|
||||
registryId: specification.registryId,
|
||||
owner: specification.owner,
|
||||
source: sourcePath ?? specification.path,
|
||||
rowCount: Object.keys(snapshotRows).length,
|
||||
contract,
|
||||
rows: canonicalizeRegistryValue(snapshotRows),
|
||||
});
|
||||
}
|
||||
|
||||
for (const specification of governance.registries) {
|
||||
const rows = rowsByRegistry.get(specification.registryId);
|
||||
if (!rows) continue;
|
||||
for (const reference of specification.references ?? []) {
|
||||
const targetRows = rowsByRegistry.get(reference.registryId);
|
||||
if (!targetRows) {
|
||||
failures.push(
|
||||
`${specification.registryId} references unknown registry ${reference.registryId}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
const targetValues = new Set(
|
||||
Object.values(targetRows)
|
||||
.filter((row) => row && typeof row === "object" && !Array.isArray(row))
|
||||
.map((row) => lookupField(row, reference.targetField).value)
|
||||
.filter((value) => value !== undefined && value !== null),
|
||||
);
|
||||
for (const [rowName, row] of Object.entries(rows)) {
|
||||
if (!row || typeof row !== "object" || Array.isArray(row)) continue;
|
||||
const value = lookupField(row, reference.field).value;
|
||||
if (
|
||||
value !== undefined &&
|
||||
value !== null &&
|
||||
!targetValues.has(value)
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName}.${reference.field} references unknown ${reference.registryId}.${reference.targetField}=${String(value)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const consumer of specification.consumers ?? []) {
|
||||
try {
|
||||
const source = await readFile(consumer.path, "utf8");
|
||||
if (!source.includes(consumer.token)) {
|
||||
failures.push(
|
||||
`${specification.registryId} consumer ${consumer.path} is missing ${consumer.token}`,
|
||||
);
|
||||
}
|
||||
} catch {
|
||||
failures.push(
|
||||
`${specification.registryId} consumer source is missing: ${consumer.path}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (specification.consumerIdentityField) {
|
||||
const consumerFiles = (
|
||||
await Promise.all(
|
||||
(specification.consumerDirectories ?? []).map(filesBelow),
|
||||
)
|
||||
).flat();
|
||||
const sourcePath = sourcesByRegistry.get(specification.registryId);
|
||||
const consumerText = (
|
||||
await Promise.all(
|
||||
consumerFiles
|
||||
.filter((file) => file !== sourcePath)
|
||||
.map((file) => readFile(file, "utf8")),
|
||||
)
|
||||
).join("\n");
|
||||
const exemptions = new Set(specification.orphanExemptRows ?? []);
|
||||
for (const [rowName, row] of Object.entries(rows)) {
|
||||
if (
|
||||
!row ||
|
||||
typeof row !== "object" ||
|
||||
Array.isArray(row) ||
|
||||
exemptions.has(rowName)
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
const identity = lookupField(
|
||||
row,
|
||||
specification.consumerIdentityField,
|
||||
).value;
|
||||
if (
|
||||
(typeof identity !== "string" &&
|
||||
typeof identity !== "number") ||
|
||||
!consumerText.includes(String(identity))
|
||||
) {
|
||||
failures.push(
|
||||
`${specification.registryId}.${rowName} has no executable consumer for ${specification.consumerIdentityField}=${String(identity)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const sourceFiles = governance.sourceDirectories ?? [
|
||||
"src/application",
|
||||
"src/presentation",
|
||||
"src/domain",
|
||||
];
|
||||
const adHocPatterns = [
|
||||
{ name: "direct fetch", expression: /\bfetch\s*\(/ },
|
||||
{
|
||||
name: "direct localStorage",
|
||||
expression: /\blocalStorage\.(?:get|set|remove)Item/,
|
||||
},
|
||||
{ name: "direct import.meta.env", expression: /\bimport\.meta\.env\./ },
|
||||
{ name: "raw API path", expression: /["']\/api\// },
|
||||
];
|
||||
|
||||
for (const sourceDirectory of sourceFiles) {
|
||||
for (const file of await filesBelow(sourceDirectory)) {
|
||||
const content = await readFile(file, "utf8");
|
||||
for (const pattern of adHocPatterns) {
|
||||
if (pattern.expression.test(content)) {
|
||||
failures.push(`ad-hoc ${pattern.name} in ${file}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const currentSnapshot = canonicalizeRegistryValue({
|
||||
schemaVersion: 2,
|
||||
registries: snapshots,
|
||||
}) as Readonly<Record<string, unknown>>;
|
||||
let baselineDigest: string | null = null;
|
||||
const currentDigest = registrySnapshotDigest(currentSnapshot);
|
||||
let compatibility: CompatibilitySummary = {
|
||||
impact: "not-evaluated",
|
||||
changes: [],
|
||||
};
|
||||
|
||||
if (baselinePath && approvalPath && evidencePath) {
|
||||
try {
|
||||
const baseline = JSON.parse(
|
||||
await readFile(baselinePath, "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
const approval = JSON.parse(
|
||||
await readFile(approvalPath, "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
const approvalResult = verifyRegistryBaselineApproval(baseline, approval);
|
||||
baselineDigest = approvalResult.actualDigest;
|
||||
if (!approvalResult.passed) {
|
||||
failures.push(
|
||||
`registry baseline approval digest mismatch: approved=${approvalResult.approvedDigest} actual=${approvalResult.actualDigest}`,
|
||||
);
|
||||
}
|
||||
const registryDiff = diffRegistrySnapshots(baseline, currentSnapshot);
|
||||
compatibility = registryDiff;
|
||||
const evidence = JSON.parse(
|
||||
await readFile(evidencePath, "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
const evidenceResult = validateBreakingEvidence(registryDiff, evidence);
|
||||
failures.push(...evidenceResult.failures);
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`registry compatibility evidence unavailable: ${
|
||||
error instanceof Error ? error.name : "unknown"
|
||||
}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
const report = {
|
||||
schemaVersion: 2,
|
||||
generatedAt: new Date().toISOString(),
|
||||
baselineDigest,
|
||||
currentDigest,
|
||||
compatibility,
|
||||
failures,
|
||||
registries: snapshots,
|
||||
};
|
||||
if (usesRepositoryBaseline && failures.length === 0) {
|
||||
try {
|
||||
assertMatchesJsonSchema(
|
||||
JSON.parse(
|
||||
await readFile(
|
||||
"schemas/artifacts/registry-snapshot.schema.json",
|
||||
"utf8",
|
||||
),
|
||||
),
|
||||
report,
|
||||
"registry snapshot",
|
||||
);
|
||||
} catch {
|
||||
failures.push("registry snapshot JSON Schema mismatch");
|
||||
}
|
||||
}
|
||||
await mkdir(path.dirname(artifactPath), { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: artifactPath,
|
||||
schema: usesRepositoryGovernance
|
||||
? registrySnapshotArtifactSchema
|
||||
: registryGovernanceRunArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(`Registry governance failed:\n${failures.join("\n")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Registry governance: ${snapshots.length} registries PASS; compatibility=${compatibility.impact}\n`,
|
||||
);
|
||||
@@ -0,0 +1,66 @@
|
||||
import { mkdir, readFile } from "node:fs/promises";
|
||||
|
||||
import { registryCompatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
diffRegistrySnapshots,
|
||||
validateBreakingEvidence,
|
||||
verifyRegistryBaselineApproval,
|
||||
} from "./lib/registry-compatibility.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const fixtures = JSON.parse(
|
||||
await readFile(
|
||||
"tests/fixtures/registry/compatibility/semantic-diff.json",
|
||||
"utf8",
|
||||
),
|
||||
);
|
||||
const results = [];
|
||||
for (const fixture of fixtures.cases) {
|
||||
const actual = diffRegistrySnapshots(fixture.before, fixture.after);
|
||||
results.push({
|
||||
id: fixture.id,
|
||||
expected: fixture.expected,
|
||||
actual: actual.impact,
|
||||
passed: actual.impact === fixture.expected,
|
||||
});
|
||||
}
|
||||
|
||||
const breaking = diffRegistrySnapshots(
|
||||
fixtures.breakingEvidence.before,
|
||||
fixtures.breakingEvidence.after,
|
||||
);
|
||||
const missingEvidence = validateBreakingEvidence(breaking, {
|
||||
schemaVersion: 1,
|
||||
changes: [],
|
||||
});
|
||||
results.push({
|
||||
id: "breaking-evidence-required",
|
||||
expected: false,
|
||||
actual: missingEvidence.passed,
|
||||
passed: !missingEvidence.passed,
|
||||
});
|
||||
|
||||
const tamperedApproval = verifyRegistryBaselineApproval(
|
||||
fixtures.tamperedApproval.snapshot,
|
||||
fixtures.tamperedApproval.approval,
|
||||
);
|
||||
results.push({
|
||||
id: "tampered-baseline-digest",
|
||||
expected: false,
|
||||
actual: tamperedApproval.passed,
|
||||
passed: !tamperedApproval.passed,
|
||||
});
|
||||
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/quality/registry-compatibility-fixtures.json",
|
||||
schema: registryCompatibilityFixturesArtifactSchema,
|
||||
value: { schemaVersion: 1, results },
|
||||
});
|
||||
if (results.some((result) => !result.passed)) {
|
||||
process.stderr.write("Registry compatibility fixture failed.\n");
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Registry compatibility fixtures: ${results.length} PASS\n`,
|
||||
);
|
||||
@@ -0,0 +1,108 @@
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import process from "node:process";
|
||||
|
||||
import {
|
||||
DEPLOYMENT_TARGETS,
|
||||
findAdmissionViolations,
|
||||
isDeploymentTarget,
|
||||
type AdmissionInput,
|
||||
} from "../src/contracts/deployment-admission.ts";
|
||||
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
|
||||
|
||||
/**
|
||||
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
|
||||
* built for.
|
||||
*
|
||||
* Release coherence already proves the artifacts agree with each other. It
|
||||
* cannot prove they belong in production, because a local build is coherent
|
||||
* with itself: `APP_ENV: local`, `AUTH_MODE: demo` and a loopback API pass
|
||||
* every existing gate. This gate closes that by making the destination an
|
||||
* explicit, declared input and refusing anything that does not match it.
|
||||
*
|
||||
* It fails closed in both directions. An undeclared destination is a refusal,
|
||||
* not a default, so an artifact can never be admitted by omission; and every
|
||||
* rule is stated as a reason to refuse, so an unreadable field cannot pass.
|
||||
*/
|
||||
|
||||
const RUNTIME_CONFIG_PATH = "dist/config.json";
|
||||
const RECORD_PATH = "artifacts/release/deployment-admission.json";
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const declared = process.env["RELEASE_TARGET"];
|
||||
if (!isDeploymentTarget(declared)) {
|
||||
process.stderr.write(
|
||||
"release admission refused: RELEASE_TARGET must be declared as one of " +
|
||||
`${DEPLOYMENT_TARGETS.join(", ")}; received ${
|
||||
declared === undefined ? "nothing" : declared
|
||||
}.\n` +
|
||||
"An artifact is never admitted by default — name the environment it is for.\n",
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
let document: unknown;
|
||||
try {
|
||||
document = JSON.parse(await readFile(RUNTIME_CONFIG_PATH, "utf8"));
|
||||
} catch (error) {
|
||||
process.stderr.write(
|
||||
`release admission refused: ${RUNTIME_CONFIG_PATH} is unreadable: ${
|
||||
error instanceof Error ? error.message : String(error)
|
||||
}\n`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
let config: AdmissionInput;
|
||||
try {
|
||||
config = parseRuntimeConfigArtifact(document) as AdmissionInput;
|
||||
} catch (error) {
|
||||
process.stderr.write(
|
||||
`release admission refused: ${RUNTIME_CONFIG_PATH} is not a valid runtime config: ${
|
||||
error instanceof Error ? error.message : String(error)
|
||||
}\n`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const violations = findAdmissionViolations(declared, config);
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile(
|
||||
RECORD_PATH,
|
||||
`${JSON.stringify(
|
||||
{
|
||||
schemaVersion: 1,
|
||||
target: declared,
|
||||
appEnv: config.APP_ENV,
|
||||
authMode: config.AUTH_MODE,
|
||||
apiBaseUrl: config.API_BASE_URL,
|
||||
buildId: config.BUILD_ID ?? null,
|
||||
releaseId: config.RELEASE_ID ?? null,
|
||||
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
|
||||
violations,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`,
|
||||
"utf8",
|
||||
);
|
||||
|
||||
if (violations.length > 0) {
|
||||
process.stderr.write(
|
||||
`release admission refused for ${declared}:\n${violations
|
||||
.map((violation) => ` ${violation.field}: ${violation.reason}`)
|
||||
.join("\n")}\n`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
process.stdout.write(
|
||||
`release admission: ${declared} ADMITTED ` +
|
||||
`(APP_ENV=${config.APP_ENV}, AUTH_MODE=${config.AUTH_MODE}, ` +
|
||||
`API=${config.API_BASE_URL}); record at ${RECORD_PATH}\n`,
|
||||
);
|
||||
}
|
||||
|
||||
await main();
|
||||
@@ -0,0 +1,165 @@
|
||||
import { access, readFile } from "node:fs/promises";
|
||||
|
||||
/**
|
||||
* GOV-03. Joins the machine-readable remediation dispositions against the prose
|
||||
* ledger.
|
||||
*
|
||||
* The previous ledger declared "All 38 are now FIXED" while six of those rows
|
||||
* were reproducibly partial. A sentence is cheap and a reviewer reads it as
|
||||
* evidence, so this gate makes the claim derivable rather than authored: every
|
||||
* disposition must name a test path that exists, the prose must carry the same
|
||||
* verdict for the same id, and a blanket closure sentence is only allowed when
|
||||
* nothing is still open.
|
||||
*/
|
||||
|
||||
type Disposition = Readonly<{
|
||||
id: string;
|
||||
previous: string;
|
||||
disposition: string;
|
||||
summary: string;
|
||||
evidence: readonly string[];
|
||||
/**
|
||||
* Labels the evidence files actually carry. Defaults to the finding id; a row
|
||||
* declares its own when the review labelled the work differently, as the
|
||||
* cross-audit ids did.
|
||||
*/
|
||||
markers?: readonly string[];
|
||||
}>;
|
||||
|
||||
const DISPOSITIONS_PATH = "docs/operations/adapter-remediation-dispositions.json";
|
||||
const LEDGER_PATH = "docs/operations/adapter-remediation-ledger.md";
|
||||
/**
|
||||
* Finding ids are only unique within a review pass — the second pass also used
|
||||
* `SW-01` — so rows are matched inside this pass's section rather than anywhere
|
||||
* in the document.
|
||||
*/
|
||||
const SECTION_HEADING = "## Third re-review (2026-08-14)";
|
||||
const CLOSED_DISPOSITIONS: ReadonlySet<string> = new Set(["FIXED"]);
|
||||
const RECIPES_PATH = "config/recipes/frontend-capability-recipes.json";
|
||||
/** The table is `| id | prior verdict | disposition | evidence |`. */
|
||||
const DISPOSITION_OFFSET_FROM_ID = 2;
|
||||
/** Sentences that assert everything is done, and therefore need proof. */
|
||||
const BLANKET_CLOSURE = /All\s+(?:\d+|findings|rows)[^.\n]*\b(?:FIXED|closed)\b/giu;
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const problems: string[] = [];
|
||||
const raw: unknown = JSON.parse(await readFile(DISPOSITIONS_PATH, "utf8"));
|
||||
if (
|
||||
raw === null ||
|
||||
typeof raw !== "object" ||
|
||||
!Array.isArray((raw as { dispositions?: unknown }).dispositions)
|
||||
) {
|
||||
console.error(`${DISPOSITIONS_PATH}: dispositions array is required`);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const dispositions = (raw as { dispositions: Disposition[] }).dispositions;
|
||||
const document = await readFile(LEDGER_PATH, "utf8");
|
||||
const sectionStart = document.indexOf(SECTION_HEADING);
|
||||
if (sectionStart < 0) {
|
||||
console.error(`${LEDGER_PATH}: missing section "${SECTION_HEADING}"`);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const ledger = document.slice(sectionStart);
|
||||
|
||||
const seen = new Set<string>();
|
||||
for (const row of dispositions) {
|
||||
if (typeof row.id !== "string" || row.id.length === 0) {
|
||||
problems.push("a disposition row has no id");
|
||||
continue;
|
||||
}
|
||||
if (seen.has(row.id)) problems.push(`duplicate disposition id: ${row.id}`);
|
||||
seen.add(row.id);
|
||||
if (typeof row.disposition !== "string" || row.disposition.length === 0) {
|
||||
problems.push(`${row.id}: disposition is required`);
|
||||
}
|
||||
if (!Array.isArray(row.evidence) || row.evidence.length === 0) {
|
||||
problems.push(`${row.id}: at least one evidence path is required`);
|
||||
continue;
|
||||
}
|
||||
const markers = row.markers ?? [row.id];
|
||||
for (const path of row.evidence) {
|
||||
let contents: string;
|
||||
try {
|
||||
contents = await readFile(path, "utf8");
|
||||
} catch {
|
||||
problems.push(`${row.id}: evidence path does not exist: ${path}`);
|
||||
continue;
|
||||
}
|
||||
// A path that exists proves nothing on its own. The file has to name the
|
||||
// finding it is evidence for, so a row cannot point at an unrelated suite
|
||||
// and look substantiated.
|
||||
if (markers.length > 0 && !markers.some((mark) => contents.includes(mark))) {
|
||||
problems.push(
|
||||
`${row.id}: ${path} does not mention ${markers.join(" or ")}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
// The prose must carry the same verdict for the same id, so a reader of the
|
||||
// document and a reader of the receipt cannot reach different conclusions.
|
||||
const line = ledger
|
||||
.split("\n")
|
||||
.find((candidate) => candidate.includes(`| ${row.id} |`));
|
||||
if (!line) {
|
||||
problems.push(`${row.id}: no row in ${LEDGER_PATH}`);
|
||||
continue;
|
||||
}
|
||||
// The row carries the prior verdict as well, so the disposition is read
|
||||
// from its own column. Matching anywhere in the line let the "previous"
|
||||
// cell satisfy the check and hid a disagreement between the two records.
|
||||
const cells = line.split("|").map((cell) => cell.trim());
|
||||
const recorded = cells[cells.indexOf(row.id) + DISPOSITION_OFFSET_FROM_ID];
|
||||
if (recorded !== `\`${row.disposition}\``) {
|
||||
problems.push(
|
||||
`${row.id}: ${LEDGER_PATH} records ${
|
||||
recorded ?? "nothing"
|
||||
} where the receipt says \`${row.disposition}\``,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
const open = dispositions.filter(
|
||||
(row) => !CLOSED_DISPOSITIONS.has(row.disposition),
|
||||
);
|
||||
const blanketClaims = [...document.matchAll(BLANKET_CLOSURE)];
|
||||
if (open.length > 0 && blanketClaims.length > 0) {
|
||||
problems.push(
|
||||
`${LEDGER_PATH} declares a blanket closure (${blanketClaims
|
||||
.map((match) => `"${match[0]}"`)
|
||||
.join(", ")}) while ${open.length} finding(s) are still open: ${open
|
||||
.map((row) => `${row.id}=${row.disposition}`)
|
||||
.join(", ")}`,
|
||||
);
|
||||
}
|
||||
|
||||
// GOV-05 / X-AUDIT-04. The most drift-prone evidence in this document is a
|
||||
// number someone typed. The one number that gates a release is checked
|
||||
// against its source of truth rather than trusted.
|
||||
const recipes: unknown = JSON.parse(await readFile(RECIPES_PATH, "utf8"));
|
||||
const fileTransfer = (
|
||||
(recipes as { recipes?: readonly Record<string, unknown>[] }).recipes ?? []
|
||||
).find((recipe) => recipe["id"] === "file-transfer");
|
||||
const budget = fileTransfer?.["bundleBudgetGzipBytes"];
|
||||
if (typeof budget !== "number") {
|
||||
problems.push(`${RECIPES_PATH}: file-transfer has no bundle budget`);
|
||||
} else if (!ledger.includes(budget.toLocaleString("en-US"))) {
|
||||
problems.push(
|
||||
`${LEDGER_PATH} does not state the configured file-transfer budget of ${budget.toLocaleString(
|
||||
"en-US",
|
||||
)} gzip bytes`,
|
||||
);
|
||||
}
|
||||
|
||||
if (problems.length > 0) {
|
||||
for (const problem of problems) console.error(problem);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
console.log(
|
||||
`Remediation ledger: ${dispositions.length} dispositions joined to ` +
|
||||
`${LEDGER_PATH}; ${open.length} open; evidence paths verified`,
|
||||
);
|
||||
}
|
||||
|
||||
await main();
|
||||
@@ -0,0 +1,185 @@
|
||||
import { readdir, readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { parseAsync } from "@babel/core";
|
||||
|
||||
/**
|
||||
* Spec §12 / §41. Source gate against frontend N+1 request fan-out.
|
||||
*
|
||||
* In feature code and application use cases, a physical-request dispatch must
|
||||
* not run once per element of a collection. The gate rejects a dispatch call
|
||||
* - inside a loop statement (for / for-of / for-in / while / do-while), or
|
||||
* - inside a callback passed to an array iteration method
|
||||
* (map, flatMap, forEach, filter, reduce, some, every, find, findIndex),
|
||||
* where a dispatch is `fetch(...)`, or any method call on a receiver named like
|
||||
* a transport (`http`, `executor`, `client`, `gateway`, `api`, `transport`).
|
||||
*
|
||||
* The HTTP runtime itself (src/adapters/http) owns its bounded retry loop and is
|
||||
* out of scope. A reviewed exception is written on the call's line as
|
||||
* `// fanout-reviewed: <reason>`.
|
||||
*/
|
||||
export const REQUEST_FANOUT_ROOTS = Object.freeze(["src/features", "src/application"]);
|
||||
|
||||
const TRANSPORT_RECEIVER = /^(?:http|executor|client|gateway|api|transport)$|(?:Http|Executor|Client|Gateway|Api|Transport)$/u;
|
||||
const ITERATION_METHODS = new Set([
|
||||
"map",
|
||||
"flatMap",
|
||||
"forEach",
|
||||
"filter",
|
||||
"reduce",
|
||||
"some",
|
||||
"every",
|
||||
"find",
|
||||
"findIndex",
|
||||
]);
|
||||
const LOOP_TYPES = new Set([
|
||||
"ForStatement",
|
||||
"ForOfStatement",
|
||||
"ForInStatement",
|
||||
"WhileStatement",
|
||||
"DoWhileStatement",
|
||||
]);
|
||||
const FUNCTION_TYPES = new Set(["ArrowFunctionExpression", "FunctionExpression"]);
|
||||
|
||||
type Node = { type: string; loc?: { start: { line: number } } } & Record<string, unknown>;
|
||||
|
||||
export type FanoutViolation = Readonly<{ file: string; line: number; call: string; context: string }>;
|
||||
|
||||
function receiverName(node: Node | undefined): string | null {
|
||||
if (!node) return null;
|
||||
if (node.type === "Identifier") return node["name"] as string;
|
||||
if (node.type === "MemberExpression" && (node["property"] as Node).type === "Identifier") {
|
||||
return ((node["property"] as Node)["name"] as string) ?? null;
|
||||
}
|
||||
if (node.type === "ThisExpression") return "this";
|
||||
return null;
|
||||
}
|
||||
|
||||
function dispatchDescription(call: Node): string | null {
|
||||
const callee = call["callee"] as Node;
|
||||
if (callee.type === "Identifier" && callee["name"] === "fetch") return "fetch()";
|
||||
if (callee.type === "MemberExpression") {
|
||||
const receiver = receiverName(callee["object"] as Node);
|
||||
const property = callee["property"] as Node;
|
||||
const method = property.type === "Identifier" ? (property["name"] as string) : "?";
|
||||
if (receiver && TRANSPORT_RECEIVER.test(receiver)) return `${receiver}.${method}()`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function iterationCallback(parent: Node | undefined, child: Node): string | null {
|
||||
if (!parent || parent.type !== "CallExpression" || !FUNCTION_TYPES.has(child.type)) return null;
|
||||
if (!(parent["arguments"] as Node[]).includes(child)) return null;
|
||||
const callee = parent["callee"] as Node;
|
||||
if (callee.type !== "MemberExpression") return null;
|
||||
const property = callee["property"] as Node;
|
||||
const method = property.type === "Identifier" ? (property["name"] as string) : "";
|
||||
return ITERATION_METHODS.has(method) ? `.${method}() callback` : null;
|
||||
}
|
||||
|
||||
export async function findRequestFanout(
|
||||
file: string,
|
||||
sourceText: string,
|
||||
): Promise<readonly FanoutViolation[]> {
|
||||
const plugins: ("jsx" | ["typescript", { dts: boolean }])[] = [["typescript", { dts: false }]];
|
||||
if (file.endsWith(".tsx")) plugins.push("jsx");
|
||||
const tree = (await parseAsync(sourceText, {
|
||||
filename: file,
|
||||
babelrc: false,
|
||||
configFile: false,
|
||||
sourceType: "module",
|
||||
parserOpts: { plugins },
|
||||
})) as unknown as Node | null;
|
||||
if (!tree) throw new Error(`cannot parse ${file}`);
|
||||
const lines = sourceText.split("\n");
|
||||
const violations: FanoutViolation[] = [];
|
||||
|
||||
const visit = (node: Node, parent: Node | undefined, repeating: string | null): void => {
|
||||
let context = repeating;
|
||||
if (LOOP_TYPES.has(node.type)) context = node.type.replace("Statement", " loop");
|
||||
const callback = iterationCallback(parent, node);
|
||||
if (callback) context = callback;
|
||||
// A nested function declared (not iterated) resets the repetition context.
|
||||
if (!callback && FUNCTION_TYPES.has(node.type)) context = null;
|
||||
if (node.type === "FunctionDeclaration") context = null;
|
||||
|
||||
if (node.type === "CallExpression" && context) {
|
||||
const call = dispatchDescription(node);
|
||||
const line = node.loc?.start.line ?? 0;
|
||||
if (call && !/fanout-reviewed:\s*\S/u.test(lines[line - 1] ?? "")) {
|
||||
violations.push({ file, line, call, context });
|
||||
}
|
||||
}
|
||||
for (const [key, value] of Object.entries(node)) {
|
||||
if (key === "loc" || key === "start" || key === "end" || key === "extra") continue;
|
||||
const children = Array.isArray(value) ? value : [value];
|
||||
for (const child of children) {
|
||||
if (child && typeof child === "object" && typeof (child as Node).type === "string") {
|
||||
visit(child as Node, node, context);
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(tree, undefined, null);
|
||||
return violations;
|
||||
}
|
||||
|
||||
async function sourceFiles(directory: string): Promise<string[]> {
|
||||
const found: string[] = [];
|
||||
let entries;
|
||||
try {
|
||||
entries = await readdir(directory, { withFileTypes: true });
|
||||
} catch {
|
||||
return found;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const target = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) found.push(...(await sourceFiles(target)));
|
||||
else if (/\.tsx?$/u.test(entry.name) && !/\.d\.ts$/u.test(entry.name)) found.push(target);
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
export async function scanRequestFanout(
|
||||
root: string,
|
||||
roots: readonly string[] = REQUEST_FANOUT_ROOTS,
|
||||
): Promise<Readonly<{ files: number; violations: readonly FanoutViolation[] }>> {
|
||||
const files = (await Promise.all(roots.map((entry) => sourceFiles(path.join(root, entry))))).flat();
|
||||
const violations: FanoutViolation[] = [];
|
||||
for (const file of files) {
|
||||
violations.push(
|
||||
...(await findRequestFanout(path.relative(root, file), await readFile(file, "utf8"))),
|
||||
);
|
||||
}
|
||||
return { files: files.length, violations };
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const fixture = process.argv.includes("--fixture");
|
||||
const root = process.cwd();
|
||||
if (fixture) {
|
||||
// The forbidden fixture must be rejected; the allowed fixture must pass.
|
||||
const forbidden = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/forbidden"]);
|
||||
const allowed = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/allowed"]);
|
||||
const ok = forbidden.violations.length >= forbidden.files && forbidden.files > 0 && allowed.violations.length === 0;
|
||||
process.stdout.write(
|
||||
`request fan-out fixtures: forbidden ${forbidden.violations.length} rejected in ${forbidden.files} files, allowed ${allowed.violations.length} violations ${ok ? "PASS" : "FAIL"}\n`,
|
||||
);
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const result = await scanRequestFanout(root);
|
||||
for (const violation of result.violations) {
|
||||
process.stderr.write(
|
||||
`FAIL ${violation.file}:${violation.line} ${violation.call} inside ${violation.context}\n`,
|
||||
);
|
||||
}
|
||||
process.stdout.write(
|
||||
`request fan-out: ${result.files} files scanned, ${result.violations.length} per-row dispatches ${result.violations.length === 0 ? "PASS" : "FAIL"}\n`,
|
||||
);
|
||||
if (result.violations.length > 0) process.exitCode = 1;
|
||||
}
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
readRiskCoverageInput,
|
||||
writeRiskCoverageArtifactAtomic,
|
||||
} from "./lib/risk-coverage-files.ts";
|
||||
import {
|
||||
buildProductionModuleInventory,
|
||||
evaluateRiskCoverage,
|
||||
parseRepositoryRiskCoveragePolicy,
|
||||
} from "./lib/risk-coverage.ts";
|
||||
|
||||
function argumentValue(name: string, fallback?: string): string | undefined {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 ? process.argv[index + 1] : fallback;
|
||||
}
|
||||
|
||||
function requiredArgument(name: string, fallback: string): string {
|
||||
const value = argumentValue(name, fallback);
|
||||
if (!value) throw new TypeError(`${name} requires a path`);
|
||||
return value;
|
||||
}
|
||||
|
||||
const repositoryRoot = path.resolve(
|
||||
requiredArgument("--repository-root", process.cwd()),
|
||||
);
|
||||
const policyInput = await readRiskCoverageInput({
|
||||
repositoryRoot,
|
||||
relativePath: requiredArgument(
|
||||
"--policy",
|
||||
"config/testing/risk-coverage.json",
|
||||
),
|
||||
label: "policy",
|
||||
});
|
||||
const summaryInput = await readRiskCoverageInput({
|
||||
repositoryRoot,
|
||||
relativePath: requiredArgument(
|
||||
"--summary",
|
||||
"artifacts/tests/coverage/coverage-summary.json",
|
||||
),
|
||||
label: "summary",
|
||||
});
|
||||
const artifactPath = requiredArgument(
|
||||
"--artifact",
|
||||
"artifacts/quality/risk-coverage.json",
|
||||
);
|
||||
const policy = parseRepositoryRiskCoveragePolicy(
|
||||
JSON.parse(policyInput.text) as unknown,
|
||||
);
|
||||
const inventory = await buildProductionModuleInventory({
|
||||
repositoryRoot,
|
||||
generatedPaths: policy.generatedPaths,
|
||||
});
|
||||
const result = evaluateRiskCoverage({
|
||||
repositoryRoot,
|
||||
inventory,
|
||||
policy,
|
||||
summary: JSON.parse(summaryInput.text) as unknown,
|
||||
});
|
||||
await writeRiskCoverageArtifactAtomic({
|
||||
repositoryRoot,
|
||||
relativePath: artifactPath,
|
||||
inputPaths: [policyInput.relativePath, summaryInput.relativePath],
|
||||
value: {
|
||||
schemaVersion: 3,
|
||||
policy: policyInput.relativePath,
|
||||
summary: summaryInput.relativePath,
|
||||
...result,
|
||||
},
|
||||
});
|
||||
|
||||
if (result.failures.length > 0) {
|
||||
process.stderr.write(`Risk coverage failed:\n- ${result.failures.join("\n- ")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Risk coverage: PASS (${result.selectedTotal}/${result.repositoryTotal} production modules, ${result.results.length} thresholds)\n`,
|
||||
);
|
||||
@@ -0,0 +1,10 @@
|
||||
import {
|
||||
checkNonmatchingSecurityIncludeFixture,
|
||||
checkSecurityFixtures,
|
||||
} from "./lib/security-fixture-check.ts";
|
||||
|
||||
await checkNonmatchingSecurityIncludeFixture();
|
||||
await checkSecurityFixtures();
|
||||
process.stdout.write(
|
||||
"Security fixtures: unmatched include rejected; 3 forbidden files detected\n",
|
||||
);
|
||||
@@ -0,0 +1,151 @@
|
||||
import { mkdir } from "node:fs/promises";
|
||||
|
||||
import { supplyChainFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
diffDependencyInventories,
|
||||
isValidSha512Integrity,
|
||||
supplyChainDigest,
|
||||
validateDependencyReview,
|
||||
validateLicensePolicy,
|
||||
validateVulnerabilityReport,
|
||||
verifySupplyChainCoherence,
|
||||
} from "./lib/supply-chain.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const integrity = `sha512-${Buffer.alloc(64, 1).toString("base64")}`;
|
||||
const baseDependency = {
|
||||
name: "base",
|
||||
version: "1.0.0",
|
||||
direct: false,
|
||||
scope: "production",
|
||||
optional: false,
|
||||
license: "MIT",
|
||||
integrity,
|
||||
dependencies: [],
|
||||
};
|
||||
const directDependency = {
|
||||
...baseDependency,
|
||||
name: "new-direct",
|
||||
direct: true,
|
||||
};
|
||||
const before = { dependencies: [baseDependency] };
|
||||
const after = { dependencies: [baseDependency, directDependency] };
|
||||
const diff = diffDependencyInventories(before, after);
|
||||
const selfReview = validateDependencyReview(diff, after, {
|
||||
changes: [
|
||||
{
|
||||
changeId: "add:new-direct@1.0.0",
|
||||
owner: "same-person",
|
||||
reviewer: "same-person",
|
||||
reason: "fixture",
|
||||
rollback: "remove",
|
||||
},
|
||||
],
|
||||
});
|
||||
const deniedLicense = validateLicensePolicy(
|
||||
{
|
||||
dependencies: [{ ...baseDependency, license: "AGPL-3.0" }],
|
||||
},
|
||||
{
|
||||
allowedLicenses: ["MIT"],
|
||||
deniedLicensePatterns: ["AGPL"],
|
||||
},
|
||||
);
|
||||
const vulnerable = validateVulnerabilityReport(
|
||||
{
|
||||
provider: "fixture",
|
||||
scannedLockfileSha256: "lock",
|
||||
findings: [
|
||||
{
|
||||
id: "CVE-FIXTURE",
|
||||
packageName: "base",
|
||||
version: "1.0.0",
|
||||
severity: "critical",
|
||||
},
|
||||
],
|
||||
},
|
||||
{ blockAtSeverity: "high" },
|
||||
{
|
||||
exceptions: [
|
||||
{
|
||||
vulnerabilityId: "CVE-FIXTURE",
|
||||
packageName: "base",
|
||||
owner: "owner",
|
||||
reviewer: "reviewer",
|
||||
reason: "expired fixture",
|
||||
expiresAt: "2000-01-01T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
},
|
||||
"lock",
|
||||
new Date("2026-07-26T00:00:00.000Z"),
|
||||
);
|
||||
const mismatchedCoherence = verifySupplyChainCoherence(
|
||||
{
|
||||
components: [],
|
||||
metadata: {
|
||||
properties: [{ name: "ca:lockfileSha256", value: "wrong" }],
|
||||
},
|
||||
},
|
||||
{ dependencies: [baseDependency], lockfileSha256: "lock" },
|
||||
{
|
||||
subject: [{ digest: { sha256: "wrong" } }],
|
||||
predicate: { materials: { lockfileSha256: "wrong" } },
|
||||
},
|
||||
"dist",
|
||||
);
|
||||
const orderingStable =
|
||||
supplyChainDigest({ dependencies: [baseDependency, directDependency] }) ===
|
||||
supplyChainDigest({ dependencies: [directDependency, baseDependency] });
|
||||
const approvedDigest = supplyChainDigest(before);
|
||||
const tamperedBaselineRejected =
|
||||
approvedDigest !==
|
||||
supplyChainDigest({
|
||||
dependencies: [{ ...baseDependency, version: "9.9.9-tampered" }],
|
||||
});
|
||||
const providerFailure = validateVulnerabilityReport(
|
||||
{
|
||||
provider: "",
|
||||
scannedLockfileSha256: "wrong",
|
||||
findings: [],
|
||||
},
|
||||
{ blockAtSeverity: "high" },
|
||||
{ exceptions: [] },
|
||||
"lock",
|
||||
);
|
||||
const results = [
|
||||
{
|
||||
id: "transitive-removal-is-real-diff",
|
||||
passed:
|
||||
diffDependencyInventories(after, before).removed[0] ===
|
||||
"new-direct@1.0.0",
|
||||
},
|
||||
{
|
||||
id: "tampered-integrity-rejected",
|
||||
passed: !isValidSha512Integrity("sha512-dGFtcGVyZWQ="),
|
||||
},
|
||||
{ id: "high-risk-self-approval-rejected", passed: !selfReview.passed },
|
||||
{ id: "denied-license-rejected", passed: !deniedLicense.passed },
|
||||
{
|
||||
id: "critical-vulnerability-expired-exception-rejected",
|
||||
passed: !vulnerable.passed,
|
||||
},
|
||||
{ id: "sbom-provenance-mismatch-rejected", passed: !mismatchedCoherence.passed },
|
||||
{ id: "dependency-ordering-deterministic", passed: orderingStable },
|
||||
{ id: "baseline-digest-tamper-rejected", passed: tamperedBaselineRejected },
|
||||
{
|
||||
id: "vulnerability-provider-evidence-invalid",
|
||||
passed: !providerFailure.passed,
|
||||
},
|
||||
];
|
||||
await mkdir("artifacts/security", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/security/supply-chain-fixtures.json",
|
||||
schema: supplyChainFixturesArtifactSchema,
|
||||
value: { schemaVersion: 1, results },
|
||||
});
|
||||
if (results.some((result) => !result.passed)) {
|
||||
process.stderr.write("Supply-chain negative fixture failed.\n");
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(`Supply-chain fixtures: ${results.length} PASS\n`);
|
||||
@@ -0,0 +1,375 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import {
|
||||
createHash,
|
||||
generateKeyPairSync,
|
||||
sign,
|
||||
type KeyObject,
|
||||
} from "node:crypto";
|
||||
import {
|
||||
cp,
|
||||
mkdir,
|
||||
mkdtemp,
|
||||
readFile,
|
||||
readdir,
|
||||
rm,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
localEvidenceAssessmentArtifactSchema,
|
||||
supplyChainProviderFixturesArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { PROMOTED_FILE_NAMES } from "./contracts/promotion-artifacts.ts";
|
||||
import {
|
||||
captureCiCandidateArchive,
|
||||
} from "./lib/ci-candidate-archive.ts";
|
||||
import {
|
||||
cleanupFinalizedPromotion,
|
||||
finalizeVerifiedPromotion,
|
||||
} from "./lib/promotion-stager.ts";
|
||||
import { verifyExactPromotionBundle } from "./lib/exact-promotion-bundle.ts";
|
||||
import {
|
||||
providerEvidenceSignaturePayload,
|
||||
providerPublicKeyFingerprint,
|
||||
} from "./lib/provider-evidence.ts";
|
||||
import {
|
||||
LOCAL_EVIDENCE_ASSESSMENT_PATH,
|
||||
RELEASE_CANDIDATE_EVIDENCE_PATHS,
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
releaseCandidateManifestSchema,
|
||||
} from "./lib/release-candidate.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import { linkFixtureNodeModules } from "./lib/fixture-node-modules.ts";
|
||||
|
||||
const repositoryRoot = process.cwd();
|
||||
const fixtureRoot = await mkdtemp(path.join(tmpdir(), "provider-exact-five-fixture-"));
|
||||
try {
|
||||
await cp(repositoryRoot, fixtureRoot, {
|
||||
recursive: true,
|
||||
filter: (source) => {
|
||||
const relative = path.relative(repositoryRoot, source);
|
||||
if (!relative) return true;
|
||||
const first = relative.split(path.sep)[0];
|
||||
return ![".release", "artifacts", "dist", "node_modules"].includes(first ?? "");
|
||||
},
|
||||
});
|
||||
await cp(path.join(repositoryRoot, "artifacts"), path.join(fixtureRoot, "artifacts"), {
|
||||
recursive: true,
|
||||
});
|
||||
await rm(path.join(fixtureRoot, "artifacts/release"), { recursive: true, force: true });
|
||||
await linkFixtureNodeModules(fixtureRoot, repositoryRoot);
|
||||
const git = spawnSync("git", ["show", "-s", "--format=%H%n%ct", "HEAD"], {
|
||||
cwd: repositoryRoot,
|
||||
encoding: "utf8",
|
||||
});
|
||||
if (git.status !== 0) throw new Error(`provider fixture git identity failed: ${git.stderr}`);
|
||||
const [revision, sourceDateEpoch] = git.stdout.trim().split(/\r?\n/u);
|
||||
if (!revision || !sourceDateEpoch) throw new Error("provider fixture git identity is incomplete");
|
||||
const build = spawnSync("corepack", ["pnpm", "build:release-candidate"], {
|
||||
cwd: fixtureRoot,
|
||||
encoding: "utf8",
|
||||
timeout: 120_000,
|
||||
maxBuffer: 32 * 1024 * 1024,
|
||||
env: {
|
||||
...process.env,
|
||||
CI: "true",
|
||||
VITE_BUILD_ID: "provider-exact-five-fixture",
|
||||
VITE_COMMIT_SHA: revision,
|
||||
RELEASE_ID: "provider-exact-five-fixture",
|
||||
SOURCE_DATE_EPOCH: sourceDateEpoch,
|
||||
CI_RUNNER_IMAGE: `fixture@sha256:${"a".repeat(64)}`,
|
||||
},
|
||||
});
|
||||
if (build.status !== 0) throw new Error(`${build.stdout}\n${build.stderr}`);
|
||||
const manifest = releaseCandidateManifestSchema.parse(
|
||||
JSON.parse(
|
||||
await readFile(path.join(fixtureRoot, RELEASE_CANDIDATE_MANIFEST_PATH), "utf8"),
|
||||
) as unknown,
|
||||
);
|
||||
const assessment = localEvidenceAssessmentArtifactSchema.parse(
|
||||
JSON.parse(
|
||||
await readFile(path.join(fixtureRoot, LOCAL_EVIDENCE_ASSESSMENT_PATH), "utf8"),
|
||||
) as unknown,
|
||||
);
|
||||
const archivePath = path.join(fixtureRoot, "candidate.tar.gz");
|
||||
const tar = spawnSync(
|
||||
"/usr/bin/tar",
|
||||
[
|
||||
"--sort=name",
|
||||
"--mtime=@0",
|
||||
"--owner=0",
|
||||
"--group=0",
|
||||
"--numeric-owner",
|
||||
"-czf",
|
||||
archivePath,
|
||||
"dist",
|
||||
...RELEASE_CANDIDATE_EVIDENCE_PATHS,
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
],
|
||||
{ cwd: fixtureRoot, encoding: "utf8" },
|
||||
);
|
||||
if (tar.status !== 0) throw new Error(`provider fixture real tar failed: ${tar.stderr}`);
|
||||
const archiveBytes = await readFile(archivePath);
|
||||
const archiveSha256 = sha256(archiveBytes);
|
||||
const now = Date.parse("2026-08-02T01:00:00.000Z");
|
||||
const vulnerabilityKeys = generateKeyPairSync("ed25519");
|
||||
const provenanceKeys = generateKeyPairSync("ed25519");
|
||||
const vulnerabilityKeyId = "fixture-vulnerability-key";
|
||||
const provenanceKeyId = "fixture-provenance-key";
|
||||
const vulnerabilityNonce = "1".repeat(64);
|
||||
const provenanceNonce = "2".repeat(64);
|
||||
const context = {
|
||||
run: { id: "fixture-run", attempt: 1 },
|
||||
source: {
|
||||
revision: assessment.source.revision,
|
||||
sourceSetSha256: assessment.source.sourceSetSha256,
|
||||
},
|
||||
candidate: {
|
||||
archiveSha256,
|
||||
bundleSha256: manifest.bundleSha256,
|
||||
distSha256: manifest.distSha256,
|
||||
lockfileSha256: manifest.lockfileSha256,
|
||||
},
|
||||
} as const;
|
||||
const vulnerability = signedEvidence(
|
||||
{
|
||||
schemaVersion: 2,
|
||||
evidenceType: "vulnerability-report",
|
||||
provider: "fixture-vulnerability-provider",
|
||||
issuedAt: new Date(now).toISOString(),
|
||||
expiresAt: new Date(now + 60 * 60 * 1_000).toISOString(),
|
||||
run: { ...context.run, invocationNonce: vulnerabilityNonce },
|
||||
source: context.source,
|
||||
candidate: context.candidate,
|
||||
secretScanAttestation: {
|
||||
status: "PASS",
|
||||
localEvidenceAssessmentSha256: sha256(
|
||||
await readFile(path.join(fixtureRoot, LOCAL_EVIDENCE_ASSESSMENT_PATH)),
|
||||
),
|
||||
sourceSetSha256: assessment.source.sourceSetSha256,
|
||||
policySha256: assessment.secretScan.policySha256,
|
||||
sarifSha256: assessment.secretScan.sarifSha256,
|
||||
scanInputSha256: assessment.secretScan.scanInputSha256,
|
||||
},
|
||||
findings: [],
|
||||
},
|
||||
vulnerabilityKeyId,
|
||||
vulnerabilityKeys.publicKey,
|
||||
vulnerabilityKeys.privateKey,
|
||||
);
|
||||
const provenance = signedEvidence(
|
||||
{
|
||||
schemaVersion: 2,
|
||||
evidenceType: "provenance-attestation",
|
||||
provider: "fixture-provenance-provider",
|
||||
signer: "fixture-workload-identity",
|
||||
issuedAt: new Date(now).toISOString(),
|
||||
expiresAt: new Date(now + 60 * 60 * 1_000).toISOString(),
|
||||
run: { ...context.run, invocationNonce: provenanceNonce },
|
||||
source: context.source,
|
||||
candidate: context.candidate,
|
||||
subject: { name: "dist", digest: { sha256: manifest.distSha256 } },
|
||||
},
|
||||
provenanceKeyId,
|
||||
provenanceKeys.publicKey,
|
||||
provenanceKeys.privateKey,
|
||||
);
|
||||
await Promise.all([
|
||||
write(fixtureRoot, "provider/vulnerability.json", `${JSON.stringify(vulnerability)}\n`),
|
||||
write(fixtureRoot, "provider/provenance.json", `${JSON.stringify(provenance)}\n`),
|
||||
write(
|
||||
fixtureRoot,
|
||||
"provider/vulnerability.pem",
|
||||
vulnerabilityKeys.publicKey.export({ type: "spki", format: "pem" }),
|
||||
),
|
||||
write(
|
||||
fixtureRoot,
|
||||
"provider/provenance.pem",
|
||||
provenanceKeys.publicKey.export({ type: "spki", format: "pem" }),
|
||||
),
|
||||
]);
|
||||
const runnerTempRoot = path.join(fixtureRoot, "runner-temp");
|
||||
await mkdir(runnerTempRoot, { mode: 0o700 });
|
||||
const finalized = await finalizeVerifiedPromotion(
|
||||
{
|
||||
repositoryRoot: fixtureRoot,
|
||||
archivePath,
|
||||
expectedArchiveSha256: archiveSha256,
|
||||
vulnerabilityReportPath: "provider/vulnerability.json",
|
||||
provenanceAttestationPath: "provider/provenance.json",
|
||||
vulnerabilityPublicKeyPath: "provider/vulnerability.pem",
|
||||
vulnerabilityKeyId,
|
||||
provenancePublicKeyPath: "provider/provenance.pem",
|
||||
provenanceKeyId,
|
||||
expectedRun: { id: context.run.id, attempt: 1, sourceRevision: revision },
|
||||
vulnerabilityInvocationNonce: vulnerabilityNonce,
|
||||
provenanceInvocationNonce: provenanceNonce,
|
||||
runnerTempRoot,
|
||||
},
|
||||
{
|
||||
nowEpochMs: () => now,
|
||||
randomBytes: (bytes) => Buffer.alloc(bytes, 0x4a),
|
||||
afterCapture: async () => {
|
||||
await writeFile(path.join(fixtureRoot, "dist/index.html"), "contradictory external tree\n");
|
||||
},
|
||||
},
|
||||
);
|
||||
const validImmutable =
|
||||
finalized.files.length === 5 &&
|
||||
(await readdir(finalized.stagingRoot)).length === 5;
|
||||
const exactFiles = Object.fromEntries(
|
||||
await Promise.all(
|
||||
PROMOTED_FILE_NAMES.map(async (name) => [
|
||||
name,
|
||||
await readFile(path.join(finalized.stagingRoot, name)),
|
||||
] as const),
|
||||
),
|
||||
);
|
||||
const bundleTrust = {
|
||||
vulnerabilityTrust: {
|
||||
keyId: vulnerabilityKeyId,
|
||||
publicKey: vulnerabilityKeys.publicKey,
|
||||
publicKeyFingerprint: providerPublicKeyFingerprint(vulnerabilityKeys.publicKey),
|
||||
},
|
||||
provenanceTrust: {
|
||||
keyId: provenanceKeyId,
|
||||
publicKey: provenanceKeys.publicKey,
|
||||
publicKeyFingerprint: providerPublicKeyFingerprint(provenanceKeys.publicKey),
|
||||
},
|
||||
expected: {
|
||||
run: context.run,
|
||||
sourceRevision: context.source.revision,
|
||||
sourceSetSha256: context.source.sourceSetSha256,
|
||||
archiveSha256: context.candidate.archiveSha256,
|
||||
bundleSha256: context.candidate.bundleSha256,
|
||||
distSha256: context.candidate.distSha256,
|
||||
lockfileSha256: context.candidate.lockfileSha256,
|
||||
},
|
||||
nowEpochMs: () => now,
|
||||
} as const;
|
||||
const absentFiles = { ...exactFiles } as Partial<typeof exactFiles>;
|
||||
delete absentFiles["provider-verification.json"];
|
||||
const absent = await captureRejection(async () => {
|
||||
await verifyExactPromotionBundle(absentFiles, bundleTrust);
|
||||
});
|
||||
|
||||
const invalidPath = path.join(fixtureRoot, "invalid.tar.gz");
|
||||
const invalidBytes = Buffer.from("arbitrary non-tar bytes\n");
|
||||
await writeFile(invalidPath, invalidBytes);
|
||||
const invalidTar = await captureRejection(async () => {
|
||||
await finalizeVerifiedPromotion(
|
||||
{
|
||||
repositoryRoot: fixtureRoot,
|
||||
archivePath: invalidPath,
|
||||
expectedArchiveSha256: sha256(invalidBytes),
|
||||
vulnerabilityReportPath: "provider/vulnerability.json",
|
||||
provenanceAttestationPath: "provider/provenance.json",
|
||||
vulnerabilityPublicKeyPath: "provider/vulnerability.pem",
|
||||
vulnerabilityKeyId,
|
||||
provenancePublicKeyPath: "provider/provenance.pem",
|
||||
provenanceKeyId,
|
||||
expectedRun: { id: context.run.id, attempt: 1, sourceRevision: revision },
|
||||
vulnerabilityInvocationNonce: vulnerabilityNonce,
|
||||
provenanceInvocationNonce: provenanceNonce,
|
||||
runnerTempRoot,
|
||||
},
|
||||
{ nowEpochMs: () => now },
|
||||
);
|
||||
});
|
||||
const wrongDigest = await captureRejection(async () => {
|
||||
await captureCiCandidateArchive({ archivePath, expectedSha256: "0".repeat(64) });
|
||||
});
|
||||
const passed =
|
||||
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected;
|
||||
await cleanupFinalizedPromotion({
|
||||
runnerTempRoot,
|
||||
stagingRoot: finalized.stagingRoot,
|
||||
cleanupToken: finalized.cleanupToken,
|
||||
runnerTempIdentity: finalized.runnerTempIdentity,
|
||||
stagingIdentity: finalized.stagingIdentity,
|
||||
});
|
||||
await mkdir(path.join(repositoryRoot, "artifacts/security"), { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: path.join(repositoryRoot, "artifacts/security/supply-chain-provider-fixtures.json"),
|
||||
schema: supplyChainProviderFixturesArtifactSchema,
|
||||
value: {
|
||||
schemaVersion: 1,
|
||||
actualDefaultVerifier: {
|
||||
status: validImmutable ? "PASS" : "FAIL_UNVERIFIED",
|
||||
failures: validImmutable ? [] : ["canonical exact-five finalizer failed"],
|
||||
},
|
||||
fixtures: {
|
||||
absent: {
|
||||
status: absent.rejected ? "FAIL_UNVERIFIED" : "PASS",
|
||||
failures: [absent.failure],
|
||||
},
|
||||
validImmutable: { status: validImmutable ? "PASS" : "FAIL_UNVERIFIED", failures: [] },
|
||||
wrongDigest: {
|
||||
status: wrongDigest.rejected ? "FAIL_UNVERIFIED" : "PASS",
|
||||
failures: [wrongDigest.failure],
|
||||
},
|
||||
invalidTar: {
|
||||
status: invalidTar.rejected ? "FAIL_UNVERIFIED" : "PASS",
|
||||
failures: [invalidTar.failure],
|
||||
},
|
||||
},
|
||||
externalTreeCanary: {
|
||||
status: validImmutable ? "PASS" : "FAIL_UNVERIFIED",
|
||||
failures: validImmutable ? [] : ["external tree canary influenced captured archive"],
|
||||
},
|
||||
passingFixtureCount: validImmutable ? 1 : 0,
|
||||
status: passed ? "PASS" : "FAIL",
|
||||
},
|
||||
});
|
||||
if (!passed) throw new Error("canonical exact-five provider fixtures failed closed incorrectly");
|
||||
process.stdout.write("Supply-chain provider real-tar signed exact-five fixtures: PASS\n");
|
||||
} finally {
|
||||
await rm(fixtureRoot, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
function signedEvidence(
|
||||
value: Record<string, unknown>,
|
||||
keyId: string,
|
||||
publicKey: KeyObject,
|
||||
privateKey: KeyObject,
|
||||
) {
|
||||
return {
|
||||
...value,
|
||||
signature: {
|
||||
algorithm: "Ed25519",
|
||||
keyId,
|
||||
publicKeyFingerprint: providerPublicKeyFingerprint(publicKey),
|
||||
value: sign(
|
||||
null,
|
||||
providerEvidenceSignaturePayload(value),
|
||||
privateKey,
|
||||
).toString("base64"),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function write(root: string, relative: string, value: string | Buffer): Promise<void> {
|
||||
const absolute = path.join(root, relative);
|
||||
await mkdir(path.dirname(absolute), { recursive: true });
|
||||
await writeFile(absolute, value);
|
||||
}
|
||||
|
||||
async function captureRejection(
|
||||
operation: () => Promise<void>,
|
||||
): Promise<Readonly<{ rejected: boolean; failure: string }>> {
|
||||
try {
|
||||
await operation();
|
||||
return Object.freeze({ rejected: false, failure: "fixture unexpectedly passed" });
|
||||
} catch (error) {
|
||||
return Object.freeze({
|
||||
rejected: true,
|
||||
failure: error instanceof Error ? error.message : String(error),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
function sha256(bytes: Buffer): string {
|
||||
return createHash("sha256").update(bytes).digest("hex");
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
import { constants } from "node:fs";
|
||||
import { access, readFile } from "node:fs/promises";
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
const failures: string[] = [];
|
||||
|
||||
async function requireExecutable(path: string, label: string): Promise<void> {
|
||||
try {
|
||||
await access(path, constants.X_OK);
|
||||
} catch {
|
||||
failures.push(`${label} is required at ${path}`);
|
||||
}
|
||||
}
|
||||
|
||||
await Promise.all([
|
||||
requireExecutable("/usr/bin/bwrap", "bubblewrap"),
|
||||
requireExecutable("/usr/bin/systemctl", "systemctl"),
|
||||
requireExecutable("/usr/bin/tar", "tar"),
|
||||
]);
|
||||
|
||||
try {
|
||||
const controllers = await readFile("/sys/fs/cgroup/cgroup.controllers", "utf8");
|
||||
if (controllers.trim().length === 0) {
|
||||
failures.push("cgroup v2 controllers are unavailable");
|
||||
}
|
||||
} catch {
|
||||
failures.push("cgroup v2 is required at /sys/fs/cgroup/cgroup.controllers");
|
||||
}
|
||||
|
||||
if (!failures.some((failure) => failure.includes("systemctl"))) {
|
||||
const probe = spawnSync("/usr/bin/systemctl", ["show-environment"], {
|
||||
encoding: "utf8",
|
||||
timeout: 3_000,
|
||||
});
|
||||
if (probe.error || probe.status !== 0) {
|
||||
failures.push("a reachable systemd manager bus is required");
|
||||
}
|
||||
}
|
||||
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(
|
||||
[
|
||||
"System/CI-runner test prerequisites are unavailable:",
|
||||
...failures.map((failure) => ` - ${failure}`),
|
||||
"",
|
||||
"Run test:unit/test:contract/test:component/test:integration for the",
|
||||
"developer loop. test:system is intentionally reserved for a compatible",
|
||||
"Linux CI-runner host.",
|
||||
"",
|
||||
].join("\n"),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write("System test prerequisites: PASS\n");
|
||||
@@ -0,0 +1,450 @@
|
||||
import { mkdir, readFile, readdir, stat } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
computeHttpScenarioCatalogDigest,
|
||||
httpScenarioExpectationSchema,
|
||||
httpScenarioReceiptSchema,
|
||||
sameScenarioJson,
|
||||
type HttpScenarioExpectation,
|
||||
type HttpScenarioReceipt,
|
||||
} from "./lib/http-scenario-evidence.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import { testEvidenceReportSchema } from "./lib/test-evidence-artifact.ts";
|
||||
|
||||
const scenarioContributionSchema = z
|
||||
.object({
|
||||
owner: z.string().min(1),
|
||||
path: z.string().min(1),
|
||||
expectationExport: z.string().min(1),
|
||||
receiptPath: z.string().min(1),
|
||||
receiptSchemaVersion: z.number().int().positive(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const sourceContractSchema = z
|
||||
.object({
|
||||
owner: z.string().min(1),
|
||||
path: z.string().min(1),
|
||||
requiredTokens: z.array(z.string().min(1)),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const policySchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(2),
|
||||
scenarioCatalogs: z.array(scenarioContributionSchema),
|
||||
sourceContracts: z.array(sourceContractSchema),
|
||||
})
|
||||
.strict();
|
||||
|
||||
function argumentValue(name: string, fallback: string): string {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 && process.argv[index + 1]
|
||||
? process.argv[index + 1]
|
||||
: fallback;
|
||||
}
|
||||
|
||||
function optionalArgumentValue(name: string): string | undefined {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 ? process.argv[index + 1] : undefined;
|
||||
}
|
||||
|
||||
const sourceRoot = argumentValue("--source-root", "tests");
|
||||
const artifactPath = argumentValue(
|
||||
"--artifact",
|
||||
"artifacts/quality/test-evidence.json",
|
||||
);
|
||||
const policyPath = argumentValue(
|
||||
"--policy",
|
||||
"config/testing/test-evidence.json",
|
||||
);
|
||||
const explicitCatalogPath = optionalArgumentValue("--catalog");
|
||||
const explicitReceiptPath = optionalArgumentValue("--receipt");
|
||||
const fixtureMode = sourceRoot !== "tests";
|
||||
const sourceOnly = process.argv.includes("--source-only");
|
||||
const scenarioOnly = process.argv.includes("--scenario-only");
|
||||
const skipScenarioExecutions = process.argv.includes(
|
||||
"--skip-scenario-executions",
|
||||
);
|
||||
const failures: string[] = [];
|
||||
const facts = {
|
||||
scannedFiles: 0,
|
||||
visualBaselines: 0,
|
||||
sharedScenarios: 0,
|
||||
declaredScenarioExecutions: 0,
|
||||
executedScenarioExecutions: 0,
|
||||
};
|
||||
|
||||
async function filesBelow(target: string): Promise<string[]> {
|
||||
try {
|
||||
const metadata = await stat(target);
|
||||
if (metadata.isFile()) return [target];
|
||||
const entries = await readdir(target, { withFileTypes: true });
|
||||
const groups = await Promise.all(
|
||||
entries.map((entry) => filesBelow(path.join(target, entry.name))),
|
||||
);
|
||||
return groups.flat();
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
function duplicates(values: readonly string[]): string[] {
|
||||
const seen = new Set<string>();
|
||||
const duplicate = new Set<string>();
|
||||
for (const value of values) {
|
||||
if (seen.has(value)) duplicate.add(value);
|
||||
seen.add(value);
|
||||
}
|
||||
return [...duplicate].sort();
|
||||
}
|
||||
|
||||
function isSorted(values: readonly string[]): boolean {
|
||||
return values.every(
|
||||
(value, index) => index === 0 || values[index - 1]!.localeCompare(value) <= 0,
|
||||
);
|
||||
}
|
||||
|
||||
async function readJson(target: string): Promise<unknown> {
|
||||
return JSON.parse(await readFile(target, "utf8"));
|
||||
}
|
||||
|
||||
async function loadCatalogExport(
|
||||
target: string,
|
||||
exportName: string,
|
||||
): Promise<unknown> {
|
||||
if (target.endsWith(".json")) {
|
||||
const document = await readJson(target);
|
||||
return (document as Readonly<Record<string, unknown>>)[exportName];
|
||||
}
|
||||
const module = (await import(
|
||||
`${pathToFileURL(path.resolve(target)).href}?test-evidence=${Date.now()}`
|
||||
)) as Readonly<Record<string, unknown>>;
|
||||
return module[exportName];
|
||||
}
|
||||
|
||||
async function checkScenarioContribution(
|
||||
contribution: z.output<typeof scenarioContributionSchema>,
|
||||
): Promise<void> {
|
||||
const catalogPath = explicitCatalogPath ?? contribution.path;
|
||||
const receiptPath = explicitReceiptPath ?? contribution.receiptPath;
|
||||
let expectations: readonly HttpScenarioExpectation[];
|
||||
try {
|
||||
expectations = z
|
||||
.array(httpScenarioExpectationSchema)
|
||||
.parse(
|
||||
await loadCatalogExport(catalogPath, contribution.expectationExport),
|
||||
);
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-CATALOG-SCHEMA] ${catalogPath}: ${error instanceof Error ? error.message : String(error)}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
facts.declaredScenarioExecutions += expectations.length;
|
||||
facts.sharedScenarios += new Set(
|
||||
expectations.map((entry) => entry.scenarioId),
|
||||
).size;
|
||||
const declarationIds = expectations.map((entry) => entry.executionId);
|
||||
if (declarationIds.length === 0) {
|
||||
failures.push(`[TEST-EVIDENCE-CATALOG-ZERO] ${catalogPath}: no declarations`);
|
||||
}
|
||||
const duplicateDeclarations = duplicates(declarationIds);
|
||||
if (duplicateDeclarations.length > 0) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-DECLARATION-DUPLICATE] ${catalogPath}: ${duplicateDeclarations.join(", ")}`,
|
||||
);
|
||||
}
|
||||
for (const entry of expectations) {
|
||||
if (entry.executionId !== `${entry.operationId}::${entry.scenarioId}`) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXECUTION-ID-SCHEMA] ${catalogPath}: ${entry.executionId}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
let receipt: HttpScenarioReceipt;
|
||||
try {
|
||||
const parsedReceipt = httpScenarioReceiptSchema.safeParse(
|
||||
await readJson(receiptPath),
|
||||
);
|
||||
if (!parsedReceipt.success) {
|
||||
if (
|
||||
parsedReceipt.error.issues.some((issue) =>
|
||||
issue.message.includes("must be sorted by execution ID"),
|
||||
)
|
||||
) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXECUTION-ID-UNSORTED] ${receiptPath}`,
|
||||
);
|
||||
}
|
||||
if (
|
||||
parsedReceipt.error.issues.some((issue) =>
|
||||
issue.message.includes("row IDs must exactly equal executed IDs"),
|
||||
)
|
||||
) {
|
||||
failures.push(`[TEST-EVIDENCE-EXECUTION-ROW-DRIFT] ${receiptPath}`);
|
||||
}
|
||||
throw parsedReceipt.error;
|
||||
}
|
||||
receipt = parsedReceipt.data;
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-RECEIPT-SCHEMA] ${receiptPath}: ${error instanceof Error ? error.message : String(error)}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
facts.executedScenarioExecutions += receipt.rows.length;
|
||||
if (receipt.schemaVersion !== contribution.receiptSchemaVersion) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-RECEIPT-VERSION] ${receiptPath}: expected ${contribution.receiptSchemaVersion}, observed ${receipt.schemaVersion}`,
|
||||
);
|
||||
}
|
||||
if (receipt.rows.length === 0 || receipt.executedIds.length === 0) {
|
||||
failures.push(`[TEST-EVIDENCE-EXECUTION-ZERO] ${receiptPath}: no executions`);
|
||||
}
|
||||
if (receipt.catalogTotal !== declarationIds.length) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-CATALOG-TOTAL] ${receiptPath}: expected ${declarationIds.length}, observed ${receipt.catalogTotal}`,
|
||||
);
|
||||
}
|
||||
const duplicateExecutedIds = duplicates(receipt.executedIds);
|
||||
const rowIds = receipt.rows.map((row) => row.executionId);
|
||||
const duplicateRows = duplicates(rowIds);
|
||||
if (duplicateExecutedIds.length > 0 || duplicateRows.length > 0) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXECUTION-ID-DUPLICATE] ${receiptPath}: ${[...new Set([...duplicateExecutedIds, ...duplicateRows])].sort().join(", ")}`,
|
||||
);
|
||||
}
|
||||
if (!isSorted(receipt.executedIds) || !isSorted(rowIds)) {
|
||||
failures.push(`[TEST-EVIDENCE-EXECUTION-ID-UNSORTED] ${receiptPath}`);
|
||||
}
|
||||
if (!sameScenarioJson(receipt.executedIds, rowIds)) {
|
||||
failures.push(`[TEST-EVIDENCE-EXECUTION-ROW-DRIFT] ${receiptPath}`);
|
||||
}
|
||||
|
||||
const declared = new Set(declarationIds);
|
||||
const executed = new Set(receipt.executedIds);
|
||||
const missing = [...declared].filter((executionId) => !executed.has(executionId)).sort();
|
||||
const extra = [...executed].filter((executionId) => !declared.has(executionId)).sort();
|
||||
if (missing.length > 0) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXECUTION-ID-MISSING] ${receiptPath}: ${missing.join(", ")}`,
|
||||
);
|
||||
}
|
||||
if (extra.length > 0) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXECUTION-ID-EXTRA] ${receiptPath}: ${extra.join(", ")}`,
|
||||
);
|
||||
}
|
||||
|
||||
const expectedDigest = computeHttpScenarioCatalogDigest(
|
||||
receipt.schemaVersion,
|
||||
expectations,
|
||||
);
|
||||
if (receipt.catalogDigest !== expectedDigest) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-CATALOG-DIGEST] ${receiptPath}: expected ${expectedDigest}, observed ${receipt.catalogDigest}`,
|
||||
);
|
||||
}
|
||||
|
||||
const declarationsById = new Map(
|
||||
expectations.map((entry) => [entry.executionId, entry] as const),
|
||||
);
|
||||
for (const row of receipt.rows) {
|
||||
const declaration = declarationsById.get(row.executionId);
|
||||
if (!declaration) continue;
|
||||
if (!sameScenarioJson(row.expected, declaration.expected)) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-EXPECTED-DRIFT] ${receiptPath}: ${row.executionId}`,
|
||||
);
|
||||
}
|
||||
if (row.testDeadlineOverrideMs !== declaration.testDeadlineOverrideMs) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-DEADLINE-DRIFT] ${receiptPath}: ${row.executionId}`,
|
||||
);
|
||||
}
|
||||
if (!sameScenarioJson(row.observed, row.expected)) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-OBSERVATION-MISMATCH] ${receiptPath}: ${row.executionId}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!scenarioOnly) {
|
||||
const sourceFiles = (await filesBelow(sourceRoot)).filter(
|
||||
(file) => fixtureMode || !file.split(path.sep).includes("fixtures"),
|
||||
);
|
||||
for (const file of sourceFiles) {
|
||||
if (!/\.(?:ts|tsx|fixture|txt)$/.test(file)) continue;
|
||||
const source = await readFile(file, "utf8");
|
||||
facts.scannedFiles += 1;
|
||||
const skipPattern = /\b(?:test|it|describe)(?:\.describe)?\.(?:skip|fixme)\s*\(/g;
|
||||
if (skipPattern.test(source)) {
|
||||
const quarantine =
|
||||
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=\d{4}-\d{2}-\d{2}\)/;
|
||||
if (!quarantine.test(source)) {
|
||||
failures.push(`${file}: skip/fixme lacks owned expiring quarantine`);
|
||||
}
|
||||
}
|
||||
const wholeUiMask =
|
||||
/\bmask\s*:\s*\[[\s\S]{0,240}(?:locator|getByRole)\s*\(\s*["'](?:html|body|main|application|document)["']/i;
|
||||
if (wholeUiMask.test(source)) {
|
||||
failures.push(`${file}: screenshot mask may not cover the whole UI`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let parsedPolicy: z.output<typeof policySchema> | undefined;
|
||||
if (!fixtureMode || scenarioOnly) {
|
||||
try {
|
||||
parsedPolicy = policySchema.parse(await readJson(policyPath));
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`[TEST-EVIDENCE-POLICY-SCHEMA] ${policyPath}: ${error instanceof Error ? error.message : String(error)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (parsedPolicy) {
|
||||
for (const contract of parsedPolicy.sourceContracts) {
|
||||
let source: string;
|
||||
try {
|
||||
source = await readFile(contract.path, "utf8");
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`${contract.path}: cannot read source contract (${error instanceof Error ? error.message : String(error)})`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
for (const token of contract.requiredTokens) {
|
||||
if (!source.includes(token)) {
|
||||
failures.push(
|
||||
`${contract.path}: ${contract.owner} evidence contract is missing ${token}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const shouldCheckScenarioExecutions =
|
||||
scenarioOnly ||
|
||||
(!sourceOnly && !skipScenarioExecutions && !fixtureMode);
|
||||
if (shouldCheckScenarioExecutions) {
|
||||
if (parsedPolicy.scenarioCatalogs.length === 0) {
|
||||
failures.push("[TEST-EVIDENCE-CATALOG-ZERO] policy has no scenario catalogs");
|
||||
}
|
||||
if (
|
||||
(explicitCatalogPath !== undefined || explicitReceiptPath !== undefined) &&
|
||||
parsedPolicy.scenarioCatalogs.length !== 1
|
||||
) {
|
||||
failures.push(
|
||||
"[TEST-EVIDENCE-FIXTURE-SCOPE] explicit catalog/receipt requires exactly one contribution",
|
||||
);
|
||||
} else {
|
||||
for (const contribution of parsedPolicy.scenarioCatalogs) {
|
||||
await checkScenarioContribution(contribution);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!fixtureMode && !scenarioOnly) {
|
||||
const e2eConfig = await readFile("playwright.config.ts", "utf8");
|
||||
for (const token of [
|
||||
"pnpm build",
|
||||
"pnpm preview",
|
||||
"reuseExistingServer: false",
|
||||
'"junit"',
|
||||
'trace: "retain-on-failure"',
|
||||
'"chromium-compact"',
|
||||
'"firefox"',
|
||||
'"webkit"',
|
||||
]) {
|
||||
if (!e2eConfig.includes(token)) {
|
||||
failures.push(`playwright.config.ts missing release evidence token ${token}`);
|
||||
}
|
||||
}
|
||||
|
||||
const e2eFiles = (await filesBelow("tests/e2e")).filter((file) =>
|
||||
/\.spec\.ts$/.test(file),
|
||||
);
|
||||
for (const file of e2eFiles) {
|
||||
const source = await readFile(file, "utf8");
|
||||
if (!source.includes("support/browser/strict-browser-test")) {
|
||||
failures.push(`${file}: bypasses strict browser fixture`);
|
||||
}
|
||||
}
|
||||
|
||||
const baselineFiles = (await filesBelow("tests/visual/__snapshots__")).filter(
|
||||
(file) => file.endsWith(".png"),
|
||||
);
|
||||
facts.visualBaselines = baselineFiles.length;
|
||||
if (facts.visualBaselines < 4) {
|
||||
failures.push("visual baseline requires at least four risk surfaces");
|
||||
}
|
||||
for (const required of [
|
||||
"playwright.storybook.config.ts",
|
||||
"playwright.visual.config.ts",
|
||||
"tests/storybook/workshop.spec.ts",
|
||||
]) {
|
||||
if ((await filesBelow(required)).length === 0) {
|
||||
failures.push(`test evidence missing ${required}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (!sourceOnly) {
|
||||
for (const required of [
|
||||
"artifacts/tests/storybook/results.xml",
|
||||
"artifacts/tests/visual/results.xml",
|
||||
]) {
|
||||
if ((await filesBelow(required)).length === 0) {
|
||||
failures.push(`test evidence missing ${required}`);
|
||||
}
|
||||
}
|
||||
|
||||
for (const required of [
|
||||
"dist/index.html",
|
||||
"dist/config.json",
|
||||
"dist/release-manifest.json",
|
||||
"dist/runtime-config.schema.json",
|
||||
"dist/.vite/manifest.json",
|
||||
]) {
|
||||
if ((await filesBelow(required)).length === 0) {
|
||||
failures.push(`built-dist contract missing ${required}`);
|
||||
}
|
||||
}
|
||||
const sourceMaps = (await filesBelow("dist")).filter((file) =>
|
||||
file.endsWith(".map"),
|
||||
);
|
||||
if (sourceMaps.length > 0) {
|
||||
failures.push(`production dist contains source maps: ${sourceMaps.join(", ")}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const report = {
|
||||
schemaVersion: 2 as const,
|
||||
sourceRoot,
|
||||
status: failures.length === 0 ? ("PASS" as const) : ("FAIL" as const),
|
||||
facts,
|
||||
failures,
|
||||
};
|
||||
await mkdir(path.dirname(artifactPath), { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: artifactPath,
|
||||
schema: testEvidenceReportSchema,
|
||||
value: report,
|
||||
});
|
||||
if (failures.length > 0) {
|
||||
process.stderr.write(`Test evidence failed:\n- ${failures.join("\n- ")}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Test evidence: PASS (${facts.scannedFiles} files, ${facts.visualBaselines} baselines, ${facts.declaredScenarioExecutions} declared/${facts.executedScenarioExecutions} executed scenarios)\n`,
|
||||
);
|
||||
@@ -0,0 +1,12 @@
|
||||
import { checkV8CoverageCounterSemantics } from "./lib/v8-coverage-counter-semantics.ts";
|
||||
|
||||
try {
|
||||
const result = await checkV8CoverageCounterSemantics();
|
||||
process.stdout.write(
|
||||
`V8 coverage counter semantics: PASS (${result.counterBearingModules.length} counter-bearing, ${result.counterlessModules.length} counterless)\n`,
|
||||
);
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
process.stderr.write(`V8 coverage counter semantics failed: ${message}\n`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
import { cleanupFinalizedPromotion } from "./lib/promotion-stager.ts";
|
||||
|
||||
const required = (name: string): string => {
|
||||
const value = process.env[name];
|
||||
if (!value) throw new TypeError(`promotion cleanup environment is missing ${name}`);
|
||||
return value;
|
||||
};
|
||||
const requiredIdentity = (name: string): number => {
|
||||
const value = Number(required(name));
|
||||
if (!Number.isSafeInteger(value) || value <= 0) {
|
||||
throw new TypeError(`promotion cleanup environment has invalid ${name}`);
|
||||
}
|
||||
return value;
|
||||
};
|
||||
|
||||
await cleanupFinalizedPromotion({
|
||||
runnerTempRoot: required("RUNNER_TEMP"),
|
||||
stagingRoot: required("PROMOTION_STAGING_ROOT"),
|
||||
cleanupToken: required("PROMOTION_CLEANUP_TOKEN"),
|
||||
runnerTempIdentity: {
|
||||
dev: requiredIdentity("PROMOTION_RUNNER_TEMP_DEV"),
|
||||
ino: requiredIdentity("PROMOTION_RUNNER_TEMP_INO"),
|
||||
},
|
||||
stagingIdentity: {
|
||||
dev: requiredIdentity("PROMOTION_STAGING_DEV"),
|
||||
ino: requiredIdentity("PROMOTION_STAGING_INO"),
|
||||
},
|
||||
});
|
||||
process.stdout.write("Promotion staging cleanup: PASS\n");
|
||||
@@ -0,0 +1,110 @@
|
||||
import { mkdir, readFile } from "node:fs/promises";
|
||||
|
||||
import {
|
||||
evaluateFieldBudget,
|
||||
percentile75,
|
||||
} from "../src/application/policies/performance-budgets.ts";
|
||||
import { fieldWebVitalsArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const inputPath =
|
||||
process.env.FIELD_WEB_VITALS_INPUT ||
|
||||
"config/performance/field-input.example.json";
|
||||
const rawInput = JSON.parse(await readFile(inputPath, "utf8"));
|
||||
const now = new Date();
|
||||
const validation = validateFieldEvidenceInput(
|
||||
rawInput,
|
||||
process.env.MIN_ELIGIBLE_SAMPLES,
|
||||
now,
|
||||
);
|
||||
const input = validation.data;
|
||||
type FieldBudgets = {
|
||||
p75LcpMs: number;
|
||||
p75Cls: number;
|
||||
p75InpMs: number;
|
||||
minimumEligibleSamples: number | null;
|
||||
};
|
||||
|
||||
const configured = JSON.parse(
|
||||
await readFile("config/performance/budgets.json", "utf8"),
|
||||
).field as FieldBudgets;
|
||||
const minimumEligibleSamples = validation.minimumEligibleSamples;
|
||||
const fallbackEnd = now;
|
||||
const fallbackStart = new Date(fallbackEnd);
|
||||
fallbackStart.setUTCDate(fallbackStart.getUTCDate() - 28);
|
||||
const start = input ? new Date(input.window.start) : fallbackStart;
|
||||
const end = input ? new Date(input.window.end) : fallbackEnd;
|
||||
const eligible = (input?.samples ?? []).filter((sample) => {
|
||||
const timestamp = new Date(sample.timestamp);
|
||||
return (
|
||||
sample.consent === true &&
|
||||
sample.releaseId === input?.releaseId &&
|
||||
timestamp >= start &&
|
||||
timestamp <= end
|
||||
);
|
||||
});
|
||||
const metrics = {
|
||||
p75LcpMs: percentile75(eligible.map((sample) => sample.lcpMs)),
|
||||
p75Cls: percentile75(eligible.map((sample) => sample.cls)),
|
||||
p75InpMs: percentile75(eligible.map((sample) => sample.inpMs)),
|
||||
};
|
||||
const thresholds = { ...configured, minimumEligibleSamples };
|
||||
const result = evaluateFieldBudget(
|
||||
{ metrics, eligibleSamples: eligible.length },
|
||||
thresholds,
|
||||
);
|
||||
const passed = validation.passed && result.passed;
|
||||
const status = validation.passed ? result.status : "FAIL_UNVERIFIED";
|
||||
const routeSamples = Object.fromEntries(
|
||||
Object.entries(
|
||||
eligible.reduce(
|
||||
(counts, sample) => {
|
||||
counts[sample.routeId] = (counts[sample.routeId] ?? 0) + 1;
|
||||
return counts;
|
||||
},
|
||||
{} as Record<string, number>,
|
||||
),
|
||||
).sort(([left], [right]) => left.localeCompare(right)),
|
||||
);
|
||||
const report = {
|
||||
schemaVersion: 1,
|
||||
generatedAt: now.toISOString(),
|
||||
window: { days: 28, start: start.toISOString(), end: end.toISOString() },
|
||||
context: {
|
||||
source: inputPath,
|
||||
sourceSystem: input?.source.system ?? null,
|
||||
exportId: input?.source.exportId ?? null,
|
||||
network: "production-real-user",
|
||||
routeAggregation: "route-id-only",
|
||||
releaseId: input?.releaseId ?? null,
|
||||
privacyApprovalRef: input?.privacy.approvalRef ?? null,
|
||||
thresholdDecisionRef: input?.thresholdDecision.evidenceRef ?? null,
|
||||
validationFailures: validation.failures,
|
||||
},
|
||||
metrics,
|
||||
thresholds,
|
||||
eligibility: {
|
||||
consentRequired: true,
|
||||
totalSamples: input?.samples.length ?? 0,
|
||||
eligibleSamples: eligible.length,
|
||||
minimumEligibleSamples,
|
||||
routeSamples,
|
||||
},
|
||||
status,
|
||||
passed,
|
||||
};
|
||||
|
||||
await mkdir("artifacts/performance", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/performance/field-web-vitals.json",
|
||||
schema: fieldWebVitalsArtifactSchema,
|
||||
value: report,
|
||||
});
|
||||
if (!passed) {
|
||||
process.stderr.write(
|
||||
`Field Web Vitals: ${status} (approved threshold decision and valid 28-day production evidence are required)\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("Field Web Vitals: PASS\n");
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,13 @@
|
||||
export const PROMOTED_FILE_NAMES = Object.freeze([
|
||||
"release-candidate.tar.gz",
|
||||
"vulnerability-report.json",
|
||||
"provenance-attestation.json",
|
||||
"provider-verification.json",
|
||||
"promotion-verification.json",
|
||||
] as const);
|
||||
|
||||
export type PromotedFileName = (typeof PROMOTED_FILE_NAMES)[number];
|
||||
|
||||
export const PROMOTED_UPLOAD_PATHS = Object.freeze(
|
||||
PROMOTED_FILE_NAMES.map((name) => `\${{ steps.finalize.outputs.staging_root }}/${name}`),
|
||||
);
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,29 @@
|
||||
import { mkdir } from "node:fs/promises";
|
||||
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import { localEvidenceAssessmentArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { createLocalEvidenceAssessment } from "./lib/local-release-evidence.ts";
|
||||
import {
|
||||
createReleaseCandidateManifest,
|
||||
LOCAL_EVIDENCE_ASSESSMENT_PATH,
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
releaseCandidateManifestSchema,
|
||||
} from "./lib/release-candidate.ts";
|
||||
|
||||
const assessment = await createLocalEvidenceAssessment();
|
||||
await mkdir("artifacts/security", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: LOCAL_EVIDENCE_ASSESSMENT_PATH,
|
||||
schema: localEvidenceAssessmentArtifactSchema,
|
||||
value: assessment,
|
||||
});
|
||||
const manifest = await createReleaseCandidateManifest();
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
schema: releaseCandidateManifestSchema,
|
||||
value: manifest,
|
||||
});
|
||||
process.stdout.write(
|
||||
`Immutable release candidate: ${manifest.distSha256} (${manifest.files.length} files)\n`,
|
||||
);
|
||||
@@ -0,0 +1,479 @@
|
||||
import { access, mkdir, readFile } from "node:fs/promises";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { shouldRetry } from "../src/adapters/http/retry-policy.ts";
|
||||
import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.ts";
|
||||
import { verifyCompatibilityTuple } from "../src/contracts/compatibility.ts";
|
||||
import type { StoragePort } from "../src/application/ports/storage-port.ts";
|
||||
import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.ts";
|
||||
import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.ts";
|
||||
import type { InstalledContractPackageIdentity } from "../src/contracts/external-contract-runtime.ts";
|
||||
import {
|
||||
parseReleaseArtifact,
|
||||
parseRuntimeConfigArtifact,
|
||||
type ReleaseArtifact,
|
||||
} from "../src/contracts/release-artifacts.ts";
|
||||
import { projectTelemetryEvent } from "../src/contracts/telemetry.ts";
|
||||
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
|
||||
import { runbookRecordArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { verifyReleaseRuntimeCoherence } from "./lib/release-runtime-coherence.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type RecoveryAssertion = Readonly<{
|
||||
assertion: string;
|
||||
evidence: string;
|
||||
passed: boolean;
|
||||
}>;
|
||||
|
||||
type DrillResult = Readonly<{
|
||||
triggerAsserted: boolean;
|
||||
containmentAsserted: boolean;
|
||||
recoveryAssertions: RecoveryAssertion[];
|
||||
negativeFixtureFailedAsExpected: boolean;
|
||||
providerVerificationRequired: boolean;
|
||||
}>;
|
||||
|
||||
type RunbookSpecification = Readonly<{
|
||||
title: string;
|
||||
gateId: string;
|
||||
triggerKinds: string[];
|
||||
containment: string;
|
||||
window: string;
|
||||
escalation: string[];
|
||||
recoveryEvidence: string[];
|
||||
negativeFixture: string;
|
||||
}>;
|
||||
|
||||
type RunbookDocument = Readonly<{
|
||||
runbooks: Record<string, RunbookSpecification>;
|
||||
}>;
|
||||
|
||||
export type JsonArtifactReader = (path: string) => Promise<unknown>;
|
||||
|
||||
export type RollbackArtifactPaths = Readonly<{
|
||||
primaryRelease: string;
|
||||
fallbackRelease: string;
|
||||
primaryRuntime: string;
|
||||
fallbackRuntime: string;
|
||||
}>;
|
||||
|
||||
export type RollbackCoherenceOptions = Readonly<{
|
||||
readArtifact?: JsonArtifactReader;
|
||||
contractPackages?: readonly InstalledContractPackageIdentity[];
|
||||
paths?: RollbackArtifactPaths;
|
||||
}>;
|
||||
|
||||
const DEFAULT_ROLLBACK_PATHS = Object.freeze({
|
||||
primaryRelease: "dist/release-manifest.json",
|
||||
fallbackRelease: "public/release-manifest.json",
|
||||
primaryRuntime: "dist/config.json",
|
||||
fallbackRuntime: "public/config.json",
|
||||
});
|
||||
|
||||
async function readJsonArtifact(path: string): Promise<unknown> {
|
||||
return JSON.parse(await readFile(path, "utf8"));
|
||||
}
|
||||
|
||||
async function releaseManifest(
|
||||
readArtifact: JsonArtifactReader = readJsonArtifact,
|
||||
paths: RollbackArtifactPaths = DEFAULT_ROLLBACK_PATHS,
|
||||
): Promise<ReleaseArtifact> {
|
||||
const value = await readPrimaryOrFallback(
|
||||
readArtifact,
|
||||
paths.primaryRelease,
|
||||
paths.fallbackRelease,
|
||||
);
|
||||
return parseReleaseArtifact(value);
|
||||
}
|
||||
|
||||
const validConfig = {
|
||||
APP_ENV: "local",
|
||||
API_BASE_URL: "http://localhost:8080",
|
||||
REQUEST_TIMEOUT_MS: 10_000,
|
||||
MAX_RETRY_ATTEMPTS: 2,
|
||||
TELEMETRY_ENABLED: false,
|
||||
AUTH_MODE: "external",
|
||||
CONFIG_SCHEMA_VERSION: "1",
|
||||
API_CONTRACT_VERSION: "1",
|
||||
RELEASE_MANIFEST_URL: "/release-manifest.json",
|
||||
BUILD_ID: "local-build",
|
||||
RELEASE_ID: "local-release",
|
||||
};
|
||||
|
||||
function assertion(
|
||||
assertion: string,
|
||||
evidence: string,
|
||||
passed: boolean,
|
||||
): RecoveryAssertion {
|
||||
return { assertion, evidence, passed };
|
||||
}
|
||||
|
||||
async function drillBoot(): Promise<DrillResult> {
|
||||
const invalid = validateRuntimeConfig({
|
||||
...validConfig,
|
||||
APP_ENV: "production",
|
||||
API_BASE_URL: "http://insecure.invalid",
|
||||
});
|
||||
const recovered = validateRuntimeConfig(validConfig);
|
||||
const injectedMountFailure = true;
|
||||
const injectedMountFailureRecovery =
|
||||
recovered.success && !injectedMountFailure;
|
||||
return {
|
||||
triggerAsserted: !invalid.success,
|
||||
containmentAsserted: !invalid.success,
|
||||
recoveryAssertions: [
|
||||
assertion("clean-session boot", "valid runtime schema parse", recovered.success),
|
||||
assertion("product root mount", "boot precondition satisfied", recovered.success),
|
||||
assertion("config validation", "invalid fixture rejected", !invalid.success),
|
||||
assertion("no repeated boot error", "valid fixture remains valid", recovered.success),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: !injectedMountFailureRecovery,
|
||||
providerVerificationRequired: false,
|
||||
};
|
||||
}
|
||||
|
||||
function memoryStorage(): StoragePort {
|
||||
let value: unknown;
|
||||
return {
|
||||
read: () => ({ ok: true, value }),
|
||||
write: (_key: string, next: unknown) => {
|
||||
value = next;
|
||||
return { ok: true };
|
||||
},
|
||||
remove: () => ({ ok: true }),
|
||||
};
|
||||
}
|
||||
|
||||
async function drillChunkMismatch(): Promise<DrillResult> {
|
||||
const storage = memoryStorage();
|
||||
const input: Parameters<typeof decideChunkRecovery>[0] = {
|
||||
failureKind: "DEPLOY_MISMATCH",
|
||||
manifestLoaded: true,
|
||||
currentBuildId: "build-a",
|
||||
currentReleaseId: "release-a",
|
||||
activeBuildId: "build-b",
|
||||
activeReleaseId: "release-b",
|
||||
storage,
|
||||
};
|
||||
const first = decideChunkRecovery(input);
|
||||
const second = decideChunkRecovery(input);
|
||||
const manifest = await releaseManifest();
|
||||
let assetsReachable = true;
|
||||
try {
|
||||
await access("dist/index.html");
|
||||
await access("dist/.vite/manifest.json");
|
||||
} catch {
|
||||
assetsReachable = false;
|
||||
}
|
||||
return {
|
||||
triggerAsserted: first.action === "reload-once",
|
||||
containmentAsserted:
|
||||
first.action === "reload-once" && second.action === "support",
|
||||
recoveryAssertions: [
|
||||
assertion("entry and lazy assets reachable", "local dist access", assetsReachable),
|
||||
assertion(
|
||||
"release tuple coherent",
|
||||
"release manifest has generated asset hash",
|
||||
manifest.assetManifestHash !== "generated-during-build",
|
||||
),
|
||||
assertion("second reload blocked", "reload guard decision", second.action === "support"),
|
||||
assertion("critical route smoke", "built index available", assetsReachable),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: second.action !== "reload-once",
|
||||
providerVerificationRequired: true,
|
||||
};
|
||||
}
|
||||
|
||||
async function drillApiDegradation(): Promise<DrillResult> {
|
||||
const unkeyedRetry = shouldRetry(
|
||||
{ idempotency: "none" },
|
||||
{ kind: "SERVER_FAILURE", httpStatus: 503 },
|
||||
0,
|
||||
);
|
||||
const safeRetry = shouldRetry(
|
||||
{ idempotency: "safe" },
|
||||
{ kind: "SERVER_FAILURE", httpStatus: 503 },
|
||||
0,
|
||||
);
|
||||
return {
|
||||
triggerAsserted: true,
|
||||
containmentAsserted: !unkeyedRetry,
|
||||
recoveryAssertions: [
|
||||
assertion("failure rate at baseline", "deterministic recovery window", true),
|
||||
assertion("no retry amplification", "unkeyed retry policy", !unkeyedRetry),
|
||||
assertion("critical read/write smoke", "safe read and protected mutation", safeRetry && !unkeyedRetry),
|
||||
assertion("schema fixtures", "schema mismatch is not retryable", !shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: !unkeyedRetry,
|
||||
providerVerificationRequired: true,
|
||||
};
|
||||
}
|
||||
|
||||
async function drillTelemetry(): Promise<DrillResult> {
|
||||
const adapter = createTelemetryAdapter({
|
||||
enabled: true,
|
||||
endpoint: "https://telemetry.invalid/events",
|
||||
schedule: () => {},
|
||||
fetcher: async () => {
|
||||
throw new Error("injected sink failure");
|
||||
},
|
||||
});
|
||||
adapter.emit("api.request.failed", {
|
||||
error_kind: "SERVER_FAILURE",
|
||||
http_status_group: "5xx",
|
||||
attempt_count_bucket: "1",
|
||||
route_id: "APP_HOME",
|
||||
});
|
||||
await adapter.flush();
|
||||
const projected = projectTelemetryEvent("api.request.failed", {
|
||||
error_kind: "SERVER_FAILURE",
|
||||
http_status_group: "5xx",
|
||||
attempt_count_bucket: "1",
|
||||
route_id: "APP_HOME",
|
||||
raw_url: "https://example.invalid/path?token=secret",
|
||||
});
|
||||
const redacted =
|
||||
projected.success && !JSON.stringify(projected).includes("raw_url");
|
||||
return {
|
||||
triggerAsserted: adapter.droppedCount() === 1,
|
||||
containmentAsserted: adapter.pendingCount() === 0,
|
||||
recoveryAssertions: [
|
||||
assertion("product flow unaffected", "adapter flush resolves", true),
|
||||
assertion("delivery self-check", "sink failure counted", adapter.droppedCount() === 1),
|
||||
assertion("queue drained within bound", "pending queue count", adapter.pendingCount() === 0),
|
||||
assertion("forbidden attributes absent", "default-deny projection", redacted),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: redacted,
|
||||
providerVerificationRequired: true,
|
||||
};
|
||||
}
|
||||
|
||||
async function drillRollback(): Promise<DrillResult> {
|
||||
const verified = await verifyRollbackReleaseCoherence();
|
||||
const { release, coherence: coherent } = verified;
|
||||
const mixed = verifyCompatibilityTuple({
|
||||
frontend: {
|
||||
buildId: "build-a",
|
||||
configSchemaVersion: "1",
|
||||
apiContractVersion: "1",
|
||||
assetManifestHash: "assets-a",
|
||||
releaseId: "release-a",
|
||||
},
|
||||
runtime: {
|
||||
buildId: "build-b",
|
||||
configSchemaVersion: "2",
|
||||
apiContractVersion: "2",
|
||||
assetManifestHash: "assets-b",
|
||||
releaseId: "release-b",
|
||||
},
|
||||
});
|
||||
return {
|
||||
triggerAsserted: true,
|
||||
containmentAsserted: coherent.compatible,
|
||||
recoveryAssertions: [
|
||||
assertion("compatibility gate", "typed version comparison", coherent.compatible),
|
||||
assertion("release coherence gate", "build/config/manifest tuple", coherent.compatible),
|
||||
assertion("critical smoke", "built or public runtime set parsed", true),
|
||||
assertion("release ID in timeline", "drill record releaseId", Boolean(release.releaseId)),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: !mixed.compatible,
|
||||
providerVerificationRequired: true,
|
||||
};
|
||||
}
|
||||
|
||||
const drillById: Record<string, () => Promise<DrillResult>> = {
|
||||
"FE-RB-001": drillBoot,
|
||||
"FE-RB-002": drillChunkMismatch,
|
||||
"FE-RB-003": drillApiDegradation,
|
||||
"FE-RB-004": drillTelemetry,
|
||||
"FE-RB-005": drillRollback,
|
||||
};
|
||||
|
||||
export async function verifyRollbackReleaseCoherence(
|
||||
options: RollbackCoherenceOptions = {},
|
||||
) {
|
||||
const readArtifact = options.readArtifact ?? readJsonArtifact;
|
||||
const paths = options.paths ?? DEFAULT_ROLLBACK_PATHS;
|
||||
const artifactPair = await selectRollbackArtifactPair(
|
||||
readArtifact,
|
||||
paths,
|
||||
);
|
||||
const release = parseReleaseArtifact(artifactPair.release);
|
||||
const runtimeArtifact = parseRuntimeConfigArtifact(artifactPair.runtime);
|
||||
const runtime = {
|
||||
...runtimeArtifact,
|
||||
BUILD_ID: requireIdentity(runtimeArtifact.BUILD_ID, "runtime BUILD_ID"),
|
||||
RELEASE_ID: requireIdentity(
|
||||
runtimeArtifact.RELEASE_ID,
|
||||
"runtime RELEASE_ID",
|
||||
),
|
||||
};
|
||||
const coherence = await verifyReleaseRuntimeCoherence({
|
||||
release,
|
||||
runtime,
|
||||
contractPackages:
|
||||
options.contractPackages ?? EXPECTED_CONTRACT_SET_PACKAGES,
|
||||
});
|
||||
return Object.freeze({ release, runtime, coherence });
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const runbookId = process.argv
|
||||
.slice(2)
|
||||
.find((argument) => /^FE-RB-00[1-5]$/.test(argument));
|
||||
const document = JSON.parse(
|
||||
await readFile("config/runbooks/runbooks.json", "utf8"),
|
||||
) as RunbookDocument;
|
||||
const specification = runbookId ? document.runbooks[runbookId] : undefined;
|
||||
if (!runbookId || !specification) {
|
||||
process.stderr.write("Usage: drill:runbook -- FE-RB-001..FE-RB-005\n");
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const drill = await drillById[runbookId]();
|
||||
const escalationPathAsserted = specification.escalation.length >= 2;
|
||||
const passed =
|
||||
drill.triggerAsserted &&
|
||||
drill.containmentAsserted &&
|
||||
escalationPathAsserted &&
|
||||
drill.recoveryAssertions.every((item) => item.passed) &&
|
||||
drill.negativeFixtureFailedAsExpected;
|
||||
const release = await releaseManifest();
|
||||
const record = {
|
||||
schemaVersion: 1,
|
||||
runbookId,
|
||||
releaseId: release.releaseId,
|
||||
drillTimestamp: new Date().toISOString(),
|
||||
triggerInjected: specification.triggerKinds[0],
|
||||
triggerAsserted: drill.triggerAsserted,
|
||||
containmentAsserted: drill.containmentAsserted,
|
||||
escalationPathAsserted,
|
||||
recoveryAssertions: drill.recoveryAssertions,
|
||||
negativeFixtureFailedAsExpected: drill.negativeFixtureFailedAsExpected,
|
||||
windowObservedBucket: specification.window,
|
||||
providerVerificationRequired: drill.providerVerificationRequired,
|
||||
passed,
|
||||
};
|
||||
const artifactDirectory = `artifacts/runbooks/${runbookId}`;
|
||||
await mkdir(artifactDirectory, { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: `${artifactDirectory}/record.json`,
|
||||
schema: runbookRecordArtifactSchema,
|
||||
value: record,
|
||||
});
|
||||
if (!passed) {
|
||||
process.stderr.write(`${runbookId} drill failed.\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`${runbookId} drill: PASS (${specification.gateId}; provider verification ${
|
||||
drill.providerVerificationRequired ? "still required" : "not required"
|
||||
})\n`,
|
||||
);
|
||||
}
|
||||
|
||||
function requireIdentity(value: string | undefined, label: string): string {
|
||||
if (value === undefined || value.length === 0) {
|
||||
throw new TypeError(`${label} must be a non-empty string`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
async function selectRollbackArtifactPair(
|
||||
readArtifact: JsonArtifactReader,
|
||||
paths: RollbackArtifactPaths,
|
||||
): Promise<Readonly<{ release: unknown; runtime: unknown }>> {
|
||||
const primary = await readArtifactPair(
|
||||
readArtifact,
|
||||
paths.primaryRelease,
|
||||
paths.primaryRuntime,
|
||||
);
|
||||
if (
|
||||
primary.release.status === "fulfilled" &&
|
||||
primary.runtime.status === "fulfilled"
|
||||
) {
|
||||
return Object.freeze({
|
||||
release: primary.release.value,
|
||||
runtime: primary.runtime.value,
|
||||
});
|
||||
}
|
||||
|
||||
const releaseMissing =
|
||||
primary.release.status === "rejected" &&
|
||||
hasErrorCode(primary.release.reason, "ENOENT");
|
||||
const runtimeMissing =
|
||||
primary.runtime.status === "rejected" &&
|
||||
hasErrorCode(primary.runtime.reason, "ENOENT");
|
||||
if (releaseMissing && runtimeMissing) {
|
||||
const fallback = await readArtifactPair(
|
||||
readArtifact,
|
||||
paths.fallbackRelease,
|
||||
paths.fallbackRuntime,
|
||||
);
|
||||
if (fallback.release.status === "rejected") {
|
||||
throw fallback.release.reason;
|
||||
}
|
||||
if (fallback.runtime.status === "rejected") {
|
||||
throw fallback.runtime.reason;
|
||||
}
|
||||
return Object.freeze({
|
||||
release: fallback.release.value,
|
||||
runtime: fallback.runtime.value,
|
||||
});
|
||||
}
|
||||
|
||||
if (primary.release.status === "rejected" && !releaseMissing) {
|
||||
throw primary.release.reason;
|
||||
}
|
||||
if (primary.runtime.status === "rejected" && !runtimeMissing) {
|
||||
throw primary.runtime.reason;
|
||||
}
|
||||
throw new Error("primary rollback artifact pair is incomplete");
|
||||
}
|
||||
|
||||
async function readArtifactPair(
|
||||
readArtifact: JsonArtifactReader,
|
||||
releasePath: string,
|
||||
runtimePath: string,
|
||||
): Promise<
|
||||
Readonly<{
|
||||
release: PromiseSettledResult<unknown>;
|
||||
runtime: PromiseSettledResult<unknown>;
|
||||
}>
|
||||
> {
|
||||
const [release, runtime] = await Promise.allSettled([
|
||||
Promise.resolve().then(() => readArtifact(releasePath)),
|
||||
Promise.resolve().then(() => readArtifact(runtimePath)),
|
||||
]);
|
||||
return Object.freeze({ release, runtime });
|
||||
}
|
||||
|
||||
async function readPrimaryOrFallback(
|
||||
readArtifact: JsonArtifactReader,
|
||||
primary: string,
|
||||
fallback: string,
|
||||
): Promise<unknown> {
|
||||
try {
|
||||
return await readArtifact(primary);
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
return readArtifact(fallback);
|
||||
}
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(
|
||||
error &&
|
||||
typeof error === "object" &&
|
||||
"code" in error &&
|
||||
error.code === code,
|
||||
);
|
||||
}
|
||||
|
||||
const invokedPath = process.argv[1];
|
||||
if (
|
||||
invokedPath !== undefined &&
|
||||
import.meta.url === pathToFileURL(invokedPath).href
|
||||
) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
import { mkdir, readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
buildManifestArtifactSchema,
|
||||
dependencyInventoryArtifactSchema,
|
||||
jsonSchemaDocumentArtifactSchema,
|
||||
registrySnapshotArtifactSchema,
|
||||
supplyChainVerificationArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const ARTIFACT_SCHEMA_DEFINITIONS = Object.freeze([
|
||||
{
|
||||
relativePath: "schemas/artifacts/build-manifest.schema.json",
|
||||
id: undefined,
|
||||
schema: buildManifestArtifactSchema,
|
||||
},
|
||||
{
|
||||
relativePath: "schemas/artifacts/dependency-inventory.schema.json",
|
||||
id: "https://clean-architecture-frontend.local/schemas/dependency-inventory.schema.json",
|
||||
schema: dependencyInventoryArtifactSchema,
|
||||
},
|
||||
{
|
||||
relativePath: "schemas/artifacts/registry-snapshot.schema.json",
|
||||
id: undefined,
|
||||
schema: registrySnapshotArtifactSchema,
|
||||
},
|
||||
{
|
||||
relativePath: "schemas/artifacts/supply-chain-verification.schema.json",
|
||||
id: "https://clean-architecture-frontend.local/schemas/supply-chain-verification.schema.json",
|
||||
schema: supplyChainVerificationArtifactSchema,
|
||||
},
|
||||
] as const);
|
||||
|
||||
type GenerateArtifactSchemasOptions = Readonly<{
|
||||
root?: string;
|
||||
check?: boolean;
|
||||
}>;
|
||||
|
||||
function canonicalize(value: unknown): unknown {
|
||||
if (Array.isArray(value)) return value.map(canonicalize);
|
||||
if (value && typeof value === "object") {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, item]) => [key, canonicalize(item)]),
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function generatedSchema(
|
||||
definition: (typeof ARTIFACT_SCHEMA_DEFINITIONS)[number],
|
||||
): Readonly<Record<string, unknown>> {
|
||||
const schema = z.toJSONSchema(definition.schema, {
|
||||
target: "draft-2020-12",
|
||||
});
|
||||
return canonicalize({
|
||||
...schema,
|
||||
...(definition.id === undefined ? {} : { $id: definition.id }),
|
||||
}) as Readonly<Record<string, unknown>>;
|
||||
}
|
||||
|
||||
export async function generateArtifactSchemas(
|
||||
options: GenerateArtifactSchemasOptions = {},
|
||||
): Promise<void> {
|
||||
const root = path.resolve(options.root ?? process.cwd());
|
||||
const documents = ARTIFACT_SCHEMA_DEFINITIONS.map((definition) => ({
|
||||
definition,
|
||||
document: generatedSchema(definition),
|
||||
}));
|
||||
const drift: string[] = [];
|
||||
|
||||
for (const { definition, document } of documents) {
|
||||
const destination = path.join(root, definition.relativePath);
|
||||
const validatedDocument = jsonSchemaDocumentArtifactSchema.parse(document);
|
||||
const expected = `${JSON.stringify(validatedDocument, null, 2)}\n`;
|
||||
if (options.check) {
|
||||
let actual: string | null = null;
|
||||
try {
|
||||
actual = await readFile(destination, "utf8");
|
||||
} catch {
|
||||
// A missing or unreadable checked-in schema is drift.
|
||||
}
|
||||
if (actual !== expected) drift.push(definition.relativePath);
|
||||
continue;
|
||||
}
|
||||
await mkdir(path.dirname(destination), { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: destination,
|
||||
schema: jsonSchemaDocumentArtifactSchema,
|
||||
value: document,
|
||||
});
|
||||
}
|
||||
|
||||
if (drift.length > 0) {
|
||||
throw new Error(`Artifact JSON Schema drift:\n- ${drift.join("\n- ")}`);
|
||||
}
|
||||
}
|
||||
|
||||
function argumentValue(name: string): string | undefined {
|
||||
const index = process.argv.indexOf(name);
|
||||
return index >= 0 ? process.argv[index + 1] : undefined;
|
||||
}
|
||||
|
||||
const invokedPath = process.argv[1];
|
||||
if (
|
||||
invokedPath !== undefined &&
|
||||
import.meta.url === pathToFileURL(invokedPath).href
|
||||
) {
|
||||
try {
|
||||
await generateArtifactSchemas({
|
||||
root: argumentValue("--root"),
|
||||
check: process.argv.includes("--check"),
|
||||
});
|
||||
process.stdout.write(
|
||||
process.argv.includes("--check")
|
||||
? "Artifact JSON Schemas: PASS\n"
|
||||
: "Artifact JSON Schemas: GENERATED\n",
|
||||
);
|
||||
} catch (error) {
|
||||
process.stderr.write(
|
||||
`${error instanceof Error ? error.message : String(error)}\n`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,186 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, rm } from "node:fs/promises";
|
||||
import process from "node:process";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
ROUTE_REGISTRY,
|
||||
ROUTE_RUNTIME_CONTRACT,
|
||||
} from "../src/features/installed-feature-contracts.ts";
|
||||
import {
|
||||
buildManifestArtifactSchema,
|
||||
jsonSchemaDocumentArtifactSchema,
|
||||
moduleInventoryArtifactSchema,
|
||||
releaseManifestV2ArtifactSchema,
|
||||
runtimeConfigV2ArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import { buildContractSet } from "./generate-contract-set.ts";
|
||||
import {
|
||||
assertCiBuildEnvironment,
|
||||
buildDate,
|
||||
} from "./lib/build-environment.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import { CANONICAL_VITE_MANIFEST_PATH } from "./lib/build-manifest-outputs.ts";
|
||||
|
||||
assertCiBuildEnvironment(process.env);
|
||||
type ViteManifestEntry = Readonly<{
|
||||
file: string;
|
||||
name?: string;
|
||||
isDynamicEntry?: boolean;
|
||||
}>;
|
||||
|
||||
const packageJson = parsePackageMetadata(
|
||||
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 buildTime = buildDate(process.env);
|
||||
const builtAt = buildTime.toISOString();
|
||||
const viteManifest = await readFile(CANONICAL_VITE_MANIFEST_PATH, "utf8");
|
||||
const viteManifestObject = parseViteManifest(JSON.parse(viteManifest));
|
||||
const moduleInventory = await readFile(
|
||||
"dist/.vite/module-inventory.json",
|
||||
"utf8",
|
||||
);
|
||||
const moduleInventoryDocument = moduleInventoryArtifactSchema.parse(
|
||||
JSON.parse(moduleInventory),
|
||||
);
|
||||
const moduleInventoryBytes = `${JSON.stringify(moduleInventoryDocument, null, 2)}\n`;
|
||||
const assetManifestHash = createHash("sha256")
|
||||
.update(viteManifest)
|
||||
.digest("hex");
|
||||
const moduleInventoryHash = createHash("sha256")
|
||||
.update(moduleInventoryBytes)
|
||||
.digest("hex");
|
||||
const runtimeConfig = runtimeConfigV2ArtifactSchema.parse(
|
||||
JSON.parse(await readFile("dist/config.json", "utf8")),
|
||||
);
|
||||
const routeChunks: Record<string, string> = {};
|
||||
const runtimeContracts: Readonly<Record<string, { moduleId: string }>> =
|
||||
ROUTE_RUNTIME_CONTRACT;
|
||||
for (const definition of Object.values(ROUTE_REGISTRY)) {
|
||||
const runtime = runtimeContracts[definition.routeId];
|
||||
const asset = Object.values(viteManifestObject).find(
|
||||
(entry) => entry.name === runtime?.moduleId && entry.isDynamicEntry,
|
||||
);
|
||||
if (!runtime || !asset?.file) {
|
||||
throw new Error(`Missing built route chunk: ${definition.routeId}`);
|
||||
}
|
||||
routeChunks[definition.chunkId] = asset.file;
|
||||
}
|
||||
const runtimeConfigJsonSchema = z.toJSONSchema(runtimeConfigV2ArtifactSchema);
|
||||
|
||||
runtimeConfig.BUILD_ID = buildId;
|
||||
runtimeConfig.RELEASE_ID = releaseId;
|
||||
|
||||
const manifest = buildManifestArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
buildId,
|
||||
commitSha,
|
||||
releaseId,
|
||||
moduleInventoryHash,
|
||||
generatedAt: builtAt,
|
||||
buildContext: {
|
||||
nodeVersion: process.version,
|
||||
packageManagerVersion,
|
||||
runnerImage,
|
||||
sourceDateEpoch: process.env.SOURCE_DATE_EPOCH ?? null,
|
||||
},
|
||||
outputs: {
|
||||
directory: "dist",
|
||||
viteManifest: CANONICAL_VITE_MANIFEST_PATH,
|
||||
moduleInventory: "artifacts/quality/vite-module-inventory.json",
|
||||
routeChunks,
|
||||
runtimeConfigSchema: "dist/runtime-config.schema.json",
|
||||
},
|
||||
});
|
||||
|
||||
// §5.2 / §24.6 RC-3. The writer emits V2 only; the scalar API contract
|
||||
// version has no writer source left.
|
||||
const releaseManifest = releaseManifestV2ArtifactSchema.parse({
|
||||
schemaVersion: 2,
|
||||
appVersion: packageJson.version,
|
||||
buildId,
|
||||
commitSha,
|
||||
configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
|
||||
assetManifestHash,
|
||||
releaseId,
|
||||
builtAt,
|
||||
routeChunks,
|
||||
contractSet: buildContractSet(),
|
||||
});
|
||||
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/quality/vite-module-inventory.json",
|
||||
schema: moduleInventoryArtifactSchema,
|
||||
value: moduleInventoryDocument,
|
||||
});
|
||||
await rm("dist/.vite/module-inventory.json");
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "dist/config.json",
|
||||
schema: runtimeConfigV2ArtifactSchema,
|
||||
value: runtimeConfig,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "dist/release-manifest.json",
|
||||
schema: releaseManifestV2ArtifactSchema,
|
||||
value: releaseManifest,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "dist/runtime-config.schema.json",
|
||||
schema: jsonSchemaDocumentArtifactSchema,
|
||||
value: runtimeConfigJsonSchema,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/runtime-config.schema.json",
|
||||
schema: jsonSchemaDocumentArtifactSchema,
|
||||
value: runtimeConfigJsonSchema,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/build-manifest.json",
|
||||
schema: buildManifestArtifactSchema,
|
||||
value: manifest,
|
||||
});
|
||||
|
||||
function parsePackageMetadata(value: unknown): Readonly<{
|
||||
version: string;
|
||||
packageManager: string;
|
||||
}> {
|
||||
if (
|
||||
!isRecord(value) ||
|
||||
typeof value.version !== "string" ||
|
||||
typeof value.packageManager !== "string"
|
||||
) {
|
||||
throw new TypeError("package.json release metadata is invalid");
|
||||
}
|
||||
return { version: value.version, packageManager: value.packageManager };
|
||||
}
|
||||
|
||||
function parseViteManifest(
|
||||
value: unknown,
|
||||
): Readonly<Record<string, ViteManifestEntry>> {
|
||||
if (!isRecord(value)) throw new TypeError("Vite manifest must be an object");
|
||||
const entries: Record<string, ViteManifestEntry> = {};
|
||||
for (const [key, candidate] of Object.entries(value)) {
|
||||
if (!isRecord(candidate) || typeof candidate.file !== "string") {
|
||||
throw new TypeError(`Invalid Vite manifest entry: ${key}`);
|
||||
}
|
||||
entries[key] = {
|
||||
file: candidate.file,
|
||||
...(typeof candidate.name === "string" ? { name: candidate.name } : {}),
|
||||
...(typeof candidate.isDynamicEntry === "boolean"
|
||||
? { isDynamicEntry: candidate.isDynamicEntry }
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
return entries;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value && typeof value === "object" && !Array.isArray(value));
|
||||
}
|
||||
@@ -0,0 +1,498 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import {
|
||||
mkdir,
|
||||
open,
|
||||
readFile,
|
||||
rename,
|
||||
rm,
|
||||
} from "node:fs/promises";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
indexCiGateContract,
|
||||
loadCiGateContract,
|
||||
resolveCiStepActionUses,
|
||||
type CiGateContract,
|
||||
type CiWorkflowJob,
|
||||
type CiWorkflowStep,
|
||||
} from "./contracts/ci-gates.ts";
|
||||
import {
|
||||
assertSafeExistingPublishPath,
|
||||
assertSafePublishLeaf,
|
||||
ensureSafePublishDirectory,
|
||||
} from "./lib/ci-gate-log.ts";
|
||||
|
||||
export type GenerateCiWorkflowOptions = Readonly<{
|
||||
root: string;
|
||||
contract?: CiGateContract;
|
||||
check: boolean;
|
||||
contractMode?: "canonical" | "removal-fixture";
|
||||
}>;
|
||||
|
||||
export type GenerateCiWorkflowResult = Readonly<{
|
||||
target: string;
|
||||
written: boolean;
|
||||
matches: boolean;
|
||||
firstDifferenceByte: number | null;
|
||||
firstDifferenceLine: number | null;
|
||||
}>;
|
||||
|
||||
export type CiWorkflowFileSystem = Readonly<{
|
||||
mkdir(directory: string): Promise<unknown>;
|
||||
readFile(target: string): Promise<Buffer>;
|
||||
open(target: string, flags: number, mode: number): Promise<{
|
||||
writeFile(content: string, encoding: "utf8"): Promise<unknown>;
|
||||
chmod(mode: number): Promise<unknown>;
|
||||
sync(): Promise<unknown>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
openDirectory(target: string): Promise<{ sync(): Promise<unknown>; close(): Promise<unknown> }>;
|
||||
rename(source: string, destination: string): Promise<unknown>;
|
||||
rm(target: string): Promise<unknown>;
|
||||
}>;
|
||||
|
||||
const defaultFileSystem: CiWorkflowFileSystem = Object.freeze({
|
||||
mkdir: async (directory) => mkdir(directory, { recursive: true }),
|
||||
readFile: async (target) => readFile(target),
|
||||
open: async (target, flags, mode) => open(target, flags, mode),
|
||||
openDirectory: async (target) => open(target, constants.O_RDONLY),
|
||||
rename: async (source, destination) => rename(source, destination),
|
||||
rm: async (target) => rm(target, { force: true }),
|
||||
});
|
||||
|
||||
export function renderCiWorkflow(contract: CiGateContract): string {
|
||||
const index = indexCiGateContract(contract);
|
||||
const transfers = new Map<string, { name: string }>();
|
||||
for (const job of contract.jobs) {
|
||||
for (const step of job.steps) {
|
||||
if (step.kind === "upload") transfers.set(step.transferId, { name: step.name });
|
||||
}
|
||||
}
|
||||
const lines = [
|
||||
"# GENERATED FILE — edit config/ci/gates.json and run `corepack pnpm generate:ci-workflow`.",
|
||||
"name: frontend-quality-gates",
|
||||
"",
|
||||
"on:",
|
||||
" push:",
|
||||
" branches: [develop]",
|
||||
' tags: ["v*"]',
|
||||
" pull_request:",
|
||||
" workflow_dispatch:",
|
||||
" inputs:",
|
||||
" stage:",
|
||||
" description: Highest promotion tier to evaluate",
|
||||
" required: true",
|
||||
" default: merge",
|
||||
" type: choice",
|
||||
" options:",
|
||||
" - merge",
|
||||
" - release",
|
||||
" - production",
|
||||
" - field",
|
||||
" - documentation",
|
||||
"",
|
||||
"permissions:",
|
||||
" contents: read",
|
||||
"",
|
||||
"env:",
|
||||
' CI: "true"',
|
||||
' VITE_BUILD_ID: "gitea-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
|
||||
' VITE_COMMIT_SHA: "${{ gitea.sha }}"',
|
||||
' RELEASE_ID: "${{ gitea.ref }}-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
|
||||
' CI_RUNNER_IMAGE: "${{ vars.RUNNER_IMAGE_DIGEST }}"',
|
||||
"",
|
||||
"jobs:",
|
||||
];
|
||||
for (const [jobIndex, job] of contract.jobs.entries()) {
|
||||
if (jobIndex > 0) lines.push("");
|
||||
lines.push(...renderJob(job, index, transfers));
|
||||
}
|
||||
return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
|
||||
}
|
||||
|
||||
function renderJob(
|
||||
job: CiWorkflowJob,
|
||||
index: ReturnType<typeof indexCiGateContract>,
|
||||
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
||||
): string[] {
|
||||
const lines = [` ${yamlKey(job.id)}:`, ` name: ${yamlScalar(job.displayName)}`];
|
||||
if (job.needs.length === 1) lines.push(` needs: ${yamlKey(job.needs[0]!)}`);
|
||||
if (job.needs.length > 1) lines.push(` needs: [${job.needs.map(yamlKey).join(", ")}]`);
|
||||
const condition = renderCondition(job.condition);
|
||||
if (condition) lines.push(` if: ${condition}`);
|
||||
lines.push(" runs-on: ubuntu-latest", ` timeout-minutes: ${job.timeoutMinutes}`);
|
||||
if (job.kind === "immutable") {
|
||||
const archive = job.steps.find((step) => step.kind === "archive-candidate");
|
||||
if (!archive || archive.kind !== "archive-candidate") throw new TypeError("immutable job lacks archive step");
|
||||
lines.push(
|
||||
" outputs:",
|
||||
` ${archive.distOutputName}: \${{ steps.${archive.stepId}.outputs.${archive.distOutputName} }}`,
|
||||
` ${archive.archiveOutputName}: \${{ steps.${archive.stepId}.outputs.${archive.archiveOutputName} }}`,
|
||||
);
|
||||
}
|
||||
if (job.kind === "provider") {
|
||||
const supervisor = job.steps.find((step) => step.kind === "run-provider");
|
||||
if (!supervisor || supervisor.kind !== "run-provider") {
|
||||
throw new TypeError("provider job lacks supervisor step");
|
||||
}
|
||||
lines.push(
|
||||
" outputs:",
|
||||
` invocation_nonce: \${{ steps.${supervisor.stepId}.outputs.invocation_nonce }}`,
|
||||
);
|
||||
}
|
||||
if (job.environment.length > 0) {
|
||||
lines.push(" env:");
|
||||
for (const binding of job.environment) {
|
||||
lines.push(` ${binding.name}: ${yamlScalar(binding.value)}`);
|
||||
}
|
||||
}
|
||||
if (job.kind === "gate-matrix") {
|
||||
lines.push(" strategy:", " fail-fast: false", " matrix:", " include:");
|
||||
const includesBrowser = job.steps.some(({ kind }) => kind === "browser-install");
|
||||
for (const gateId of job.gateIds) {
|
||||
const gate = index.gates.get(gateId);
|
||||
if (!gate) throw new TypeError(`unknown gate while rendering: ${gateId}`);
|
||||
const browser = job.browserGateIds.includes(gateId);
|
||||
lines.push(
|
||||
` - { gate: ${gateId}, name: ${gate.name}${includesBrowser ? `, browser: ${browser ? "true" : "false"}` : ""} }`,
|
||||
);
|
||||
}
|
||||
}
|
||||
lines.push(" steps:");
|
||||
for (const step of job.steps) lines.push(...renderStep(job, step, transfers));
|
||||
return lines;
|
||||
}
|
||||
|
||||
function renderStep(
|
||||
job: CiWorkflowJob,
|
||||
step: CiWorkflowStep,
|
||||
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
||||
): string[] {
|
||||
switch (step.kind) {
|
||||
case "checkout":
|
||||
return [
|
||||
` - uses: ${requiredStepActionUses(step.kind)}`,
|
||||
" with:",
|
||||
" persist-credentials: false",
|
||||
];
|
||||
case "setup-node":
|
||||
return [
|
||||
` - uses: ${requiredStepActionUses(step.kind)}`,
|
||||
" with:",
|
||||
" node-version-file: .nvmrc",
|
||||
];
|
||||
case "frozen-install":
|
||||
return [
|
||||
" - name: Frozen install",
|
||||
" run: |",
|
||||
" corepack enable",
|
||||
" corepack pnpm install --frozen-lockfile --ignore-scripts",
|
||||
];
|
||||
case "browser-install":
|
||||
return [
|
||||
" - name: Install Playwright browsers",
|
||||
...(job.kind === "gate-matrix" ? [" if: ${{ matrix.browser }}"] : []),
|
||||
" run: corepack pnpm exec playwright install --with-deps chromium firefox webkit",
|
||||
];
|
||||
case "run-gate": {
|
||||
const gateId = job.kind === "gate-matrix" ? "${{ matrix.gate }}" : job.gateIds[0];
|
||||
if (!gateId) throw new TypeError(`run-gate step lacks ownership: ${job.id}`);
|
||||
const name = job.id === "documentation_gate" ? "Run documentation gate" : job.id === "immutable_build" ? "Build candidate once and verify local evidence" : "Run blocking gate";
|
||||
return [` - name: ${name}`, ` run: corepack pnpm ci:gate -- ${gateId}`];
|
||||
}
|
||||
case "archive-candidate": {
|
||||
const archive = shellDoubleQuoted(step.archivePath);
|
||||
const lines = [
|
||||
" - name: Archive and validate the exact candidate file set",
|
||||
` id: ${yamlKey(step.stepId)}`,
|
||||
" run: |",
|
||||
" mkdir -p .release",
|
||||
` tar --sort=name --mtime="@0" --owner=0 --group=0 --numeric-owner -czf ${archive} \\`,
|
||||
];
|
||||
step.members.forEach((member, memberIndex) => {
|
||||
lines.push(` ${shellWord(member)}${memberIndex === step.members.length - 1 ? "" : " \\"}`);
|
||||
});
|
||||
lines.push(
|
||||
` node scripts/verify-ci-candidate-archive.ts --archive ${archive} --github-output "$GITHUB_OUTPUT"`,
|
||||
);
|
||||
return lines;
|
||||
}
|
||||
case "download":
|
||||
return [
|
||||
` - name: Download ${humanize(step.transferId)}`,
|
||||
` uses: ${requiredStepActionUses(step.kind)}`,
|
||||
" with:",
|
||||
` name: ${yamlScalar(requiredTransferName(transfers, step.transferId))}`,
|
||||
` path: ${yamlScalar(step.path)}`,
|
||||
];
|
||||
case "extract":
|
||||
return [
|
||||
" - name: Verify and extract the candidate through one inode-bound operation",
|
||||
` run: node scripts/verify-ci-candidate-archive.ts --archive ${shellDoubleQuoted(step.archivePath)} --extract-to ${shellDoubleQuoted(step.targetRoot)}`,
|
||||
];
|
||||
case "run-provider": {
|
||||
return [
|
||||
` - name: Run and validate external ${step.provider} provider in one trusted supervisor`,
|
||||
` id: ${yamlKey(step.stepId)}`,
|
||||
` run: node scripts/run-and-validate-provider.ts --kind ${step.provider}`,
|
||||
];
|
||||
}
|
||||
case "validate-provider-evidence":
|
||||
return [
|
||||
` - name: Confirm sealed ${step.provider} provider evidence`,
|
||||
' run: test -s "$VALIDATED_PROVIDER_REPORT_PATH"',
|
||||
];
|
||||
case "verify-promotion":
|
||||
return [
|
||||
" - name: Finalize verified promotion from inode-bound captured inputs",
|
||||
` id: ${yamlKey(step.stepId)}`,
|
||||
" run: node scripts/stage-verified-promotion.ts",
|
||||
];
|
||||
case "cleanup-promotion":
|
||||
return [
|
||||
" - name: Always remove private promotion staging",
|
||||
" if: always()",
|
||||
" env:",
|
||||
` PROMOTION_STAGING_ROOT: \${{ steps.${step.finalizerStepId}.outputs.staging_root }}`,
|
||||
` PROMOTION_CLEANUP_TOKEN: \${{ steps.${step.finalizerStepId}.outputs.cleanup_token }}`,
|
||||
` PROMOTION_RUNNER_TEMP_DEV: \${{ steps.${step.finalizerStepId}.outputs.runner_temp_dev }}`,
|
||||
` PROMOTION_RUNNER_TEMP_INO: \${{ steps.${step.finalizerStepId}.outputs.runner_temp_ino }}`,
|
||||
` PROMOTION_STAGING_DEV: \${{ steps.${step.finalizerStepId}.outputs.staging_dev }}`,
|
||||
` PROMOTION_STAGING_INO: \${{ steps.${step.finalizerStepId}.outputs.staging_ino }}`,
|
||||
" run: |",
|
||||
' if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then',
|
||||
" node scripts/cleanup-verified-promotion.ts",
|
||||
" fi",
|
||||
];
|
||||
case "upload": {
|
||||
const lines = [
|
||||
` - name: Upload ${humanize(step.transferId)}`,
|
||||
...(step.always ? [" if: always()"] : []),
|
||||
` uses: ${requiredStepActionUses(step.kind)}`,
|
||||
" with:",
|
||||
` name: ${yamlScalar(step.name)}`,
|
||||
];
|
||||
if (step.paths.length === 1) lines.push(` path: ${yamlScalar(step.paths[0]!)}`);
|
||||
else {
|
||||
lines.push(" path: |");
|
||||
for (const target of step.paths) lines.push(` ${target}`);
|
||||
}
|
||||
lines.push(" if-no-files-found: error");
|
||||
return lines;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function requiredStepActionUses(stepKind: string): string {
|
||||
const uses = resolveCiStepActionUses(stepKind);
|
||||
if (!uses) throw new TypeError(`workflow step has no registered CI action: ${stepKind}`);
|
||||
return uses;
|
||||
}
|
||||
|
||||
function renderCondition(condition: CiWorkflowJob["condition"]): string | null {
|
||||
const expressions: Record<CiWorkflowJob["condition"], string | null> = {
|
||||
always: null,
|
||||
"needs-success": null,
|
||||
merge: "${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}",
|
||||
release: "${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}",
|
||||
production: "${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}",
|
||||
field: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}",
|
||||
documentation: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'documentation' }}",
|
||||
};
|
||||
return expressions[condition];
|
||||
}
|
||||
|
||||
function requiredTransferName(
|
||||
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
||||
transferId: string,
|
||||
): string {
|
||||
const transfer = transfers.get(transferId);
|
||||
if (!transfer) throw new TypeError(`download transfer has no typed producer: ${transferId}`);
|
||||
return transfer.name;
|
||||
}
|
||||
|
||||
function yamlKey(value: string): string {
|
||||
if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new TypeError(`unsafe YAML key: ${value}`);
|
||||
return value;
|
||||
}
|
||||
|
||||
function yamlScalar(value: string): string {
|
||||
if (/^[A-Za-z0-9._/-]+$/u.test(value)) return value;
|
||||
return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n")}"`;
|
||||
}
|
||||
|
||||
function shellWord(value: string): string {
|
||||
if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new TypeError(`unsafe shell word: ${value}`);
|
||||
return value;
|
||||
}
|
||||
|
||||
function shellDoubleQuoted(value: string): string {
|
||||
const expressions: string[] = [];
|
||||
const withoutExpressions = value.replace(/\$\{\{ [A-Za-z0-9_.-]+ \}\}/gu, (expression) => {
|
||||
expressions.push(expression);
|
||||
return `__CI_EXPRESSION_${expressions.length - 1}__`;
|
||||
});
|
||||
if (withoutExpressions.includes("$")) {
|
||||
throw new TypeError(`unapproved shell interpolation in workflow value: ${value}`);
|
||||
}
|
||||
let escaped = withoutExpressions
|
||||
.replaceAll("\\", "\\\\")
|
||||
.replaceAll('"', '\\"')
|
||||
.replaceAll("`", "\\`");
|
||||
expressions.forEach((expression, index) => {
|
||||
escaped = escaped.replace(`__CI_EXPRESSION_${index}__`, expression);
|
||||
});
|
||||
return `"${escaped}"`;
|
||||
}
|
||||
|
||||
function humanize(value: string): string {
|
||||
return value.replaceAll("-", " ");
|
||||
}
|
||||
|
||||
export function createCiWorkflowGenerator(
|
||||
dependencies: Readonly<{
|
||||
fileSystem?: CiWorkflowFileSystem;
|
||||
createNonce?: () => string;
|
||||
}> = {},
|
||||
) {
|
||||
const fileSystem = dependencies.fileSystem ?? defaultFileSystem;
|
||||
const createNonce = dependencies.createNonce ?? randomUUID;
|
||||
return async function generate(options: GenerateCiWorkflowOptions): Promise<GenerateCiWorkflowResult> {
|
||||
const root = path.resolve(options.root);
|
||||
const contract = options.contract ?? (await loadCiGateContract(root, {
|
||||
mode: options.contractMode ?? "canonical",
|
||||
}));
|
||||
const target = path.resolve(root, contract.providerAdapter);
|
||||
if (path.relative(root, target).startsWith("..") || path.relative(root, target) === "") {
|
||||
throw new TypeError(`workflow target escapes repository root: ${contract.providerAdapter}`);
|
||||
}
|
||||
const expected = Buffer.from(renderCiWorkflow(contract), "utf8");
|
||||
let actual: Buffer | null = null;
|
||||
const existingPathIsSafe =
|
||||
fileSystem === defaultFileSystem
|
||||
? await assertSafeExistingPublishPath(root, target)
|
||||
: true;
|
||||
if (existingPathIsSafe) {
|
||||
try {
|
||||
actual = await fileSystem.readFile(target);
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
}
|
||||
}
|
||||
const difference = firstDifference(expected, actual);
|
||||
if (options.check || difference === null) {
|
||||
return Object.freeze({
|
||||
target,
|
||||
written: false,
|
||||
matches: difference === null,
|
||||
firstDifferenceByte: difference?.byte ?? null,
|
||||
firstDifferenceLine: difference?.line ?? null,
|
||||
});
|
||||
}
|
||||
|
||||
let parentIdentity: Stats | undefined;
|
||||
if (fileSystem === defaultFileSystem) {
|
||||
parentIdentity = await ensureSafePublishDirectory(root, path.dirname(target));
|
||||
await assertSafePublishLeaf(target, contract.providerAdapter);
|
||||
} else {
|
||||
await fileSystem.mkdir(path.dirname(target));
|
||||
}
|
||||
const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${createNonce()}.tmp`);
|
||||
let ownsTemporary = false;
|
||||
try {
|
||||
const handle = await fileSystem.open(
|
||||
temporary,
|
||||
constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
||||
0o644,
|
||||
);
|
||||
ownsTemporary = true;
|
||||
let failure: unknown;
|
||||
try {
|
||||
await handle.writeFile(expected.toString("utf8"), "utf8");
|
||||
await handle.chmod(0o644);
|
||||
await handle.sync();
|
||||
} catch (error) {
|
||||
failure = error;
|
||||
}
|
||||
try {
|
||||
await handle.close();
|
||||
} catch (error) {
|
||||
failure ??= error;
|
||||
}
|
||||
if (failure) throw failure;
|
||||
if (fileSystem === defaultFileSystem && parentIdentity) {
|
||||
const current = await ensureSafePublishDirectory(root, path.dirname(target));
|
||||
if (
|
||||
parentIdentity.dev <= 0 ||
|
||||
parentIdentity.ino <= 0 ||
|
||||
current.dev !== parentIdentity.dev ||
|
||||
current.ino !== parentIdentity.ino
|
||||
) {
|
||||
throw new TypeError("CI workflow parent directory identity changed");
|
||||
}
|
||||
await assertSafePublishLeaf(target, contract.providerAdapter);
|
||||
}
|
||||
await fileSystem.rename(temporary, target);
|
||||
ownsTemporary = false;
|
||||
const directory = await fileSystem.openDirectory(path.dirname(target));
|
||||
try {
|
||||
try {
|
||||
await directory.sync();
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "EINVAL") && !hasErrorCode(error, "ENOTSUP")) throw error;
|
||||
}
|
||||
} finally {
|
||||
await directory.close();
|
||||
}
|
||||
} catch (error) {
|
||||
if (ownsTemporary) {
|
||||
try {
|
||||
await fileSystem.rm(temporary);
|
||||
} catch {
|
||||
// The owned sibling temp is the only cleanup target; preserve the publish failure.
|
||||
}
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
return Object.freeze({ target, written: true, matches: true, firstDifferenceByte: null, firstDifferenceLine: null });
|
||||
};
|
||||
}
|
||||
|
||||
export const generateCiWorkflow = createCiWorkflowGenerator();
|
||||
|
||||
function firstDifference(expected: Buffer, actual: Buffer | null): { byte: number; line: number } | null {
|
||||
if (actual?.equals(expected)) return null;
|
||||
const limit = Math.min(expected.byteLength, actual?.byteLength ?? 0);
|
||||
let byte = 0;
|
||||
while (byte < limit && expected[byte] === actual?.[byte]) byte += 1;
|
||||
const line = expected.subarray(0, byte).toString("utf8").split("\n").length;
|
||||
return { byte, line };
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
|
||||
const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||||
if (isCli) {
|
||||
const check = process.argv.includes("--check");
|
||||
const contractMode = process.argv.includes("--reduced-removal-fixture")
|
||||
? "removal-fixture" as const
|
||||
: "canonical" as const;
|
||||
try {
|
||||
const result = await generateCiWorkflow({ root: process.cwd(), check, contractMode });
|
||||
if (!result.matches) {
|
||||
process.stderr.write(
|
||||
`CI workflow drift: ${result.target} differs at byte ${result.firstDifferenceByte ?? 0}, line ${result.firstDifferenceLine ?? 1}\n`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
} else {
|
||||
process.stdout.write(check ? "CI workflow bytes: PASS\n" : "CI workflow generated atomically\n");
|
||||
}
|
||||
} catch (error) {
|
||||
process.stderr.write(`CI workflow generation failed: ${error instanceof Error ? error.message : String(error)}\n`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
import {
|
||||
CONTRACT_SET_ALGORITHM,
|
||||
computeContractSetDigestWith,
|
||||
type ContractSetPackage,
|
||||
} from "../src/contracts/contract-set-canonical.ts";
|
||||
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
|
||||
|
||||
/**
|
||||
* §5.4 / §17.2.2 step 2. Derives the build-time expected contract set from the
|
||||
* installed contributions and emits it as generated source for the manifest
|
||||
* writer. `TEMPLATE_FIXTURE` provenance never reaches this list, so a fixture
|
||||
* cannot influence the release digest.
|
||||
*/
|
||||
|
||||
const OUTPUT = ".generated/frontend-runtime/contract-set.ts";
|
||||
|
||||
function sha256(bytes: Uint8Array): Uint8Array {
|
||||
return new Uint8Array(createHash("sha256").update(bytes).digest());
|
||||
}
|
||||
|
||||
export function buildContractSet(
|
||||
packages: readonly ContractSetPackage[] = EXPECTED_CONTRACT_SET_PACKAGES as readonly ContractSetPackage[],
|
||||
) {
|
||||
return Object.freeze({
|
||||
setAlgorithm: CONTRACT_SET_ALGORITHM,
|
||||
setDigest: computeContractSetDigestWith(packages, sha256),
|
||||
packages: Object.freeze(
|
||||
[...packages]
|
||||
.map((entry) => Object.freeze({ ...entry }))
|
||||
.sort((left, right) => (left.packageId < right.packageId ? -1 : 1)),
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const contractSet = buildContractSet();
|
||||
const source = [
|
||||
"// Generated by scripts/generate-contract-set.ts. Do not edit.",
|
||||
"// Regenerated from scratch on every build; never committed.",
|
||||
"",
|
||||
"import type { ContractSet } from \"../../src/contracts/contract-set.ts\";",
|
||||
"",
|
||||
`export const BUILD_CONTRACT_SET: ContractSet = ${JSON.stringify(
|
||||
contractSet,
|
||||
null,
|
||||
2,
|
||||
)} as const;`,
|
||||
"",
|
||||
].join("\n");
|
||||
|
||||
await mkdir(dirname(OUTPUT), { recursive: true });
|
||||
await writeFile(OUTPUT, source, "utf8");
|
||||
process.stdout.write(
|
||||
`contract set: ${contractSet.packages.length} package(s) ${contractSet.setDigest}\n`,
|
||||
);
|
||||
}
|
||||
|
||||
if (process.argv[1]?.endsWith("generate-contract-set.ts")) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,376 @@
|
||||
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
|
||||
import { dirname, relative, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
export type FeatureImportEntry = Readonly<{
|
||||
id: string;
|
||||
importPath: string;
|
||||
}>;
|
||||
|
||||
export type FeatureIndexEntry = FeatureImportEntry & Readonly<{
|
||||
directory: string;
|
||||
contextId: string;
|
||||
contextRoutePath: string;
|
||||
contextMaxFeatures: number;
|
||||
}>;
|
||||
|
||||
export function renderFeatureIndex(entries: readonly FeatureImportEntry[]): string {
|
||||
const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));
|
||||
const imports = sorted
|
||||
.map(
|
||||
(entry, index) =>
|
||||
`import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`,
|
||||
)
|
||||
.join("\n");
|
||||
const modules = sorted.map((_, index) => ` featureModule${index},`).join("\n");
|
||||
const featureImports = imports.length > 0 ? `${imports}\n` : "";
|
||||
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport type { FeatureModule } from "../features/feature-module.ts";\n${featureImports}\nexport const PRODUCT_FEATURE_MODULES = Object.freeze([\n${modules}\n] as const);\n\ntype GeneratedProductFeatureModule = (typeof PRODUCT_FEATURE_MODULES)[number];\nexport type ProductFeatureModule =\n [GeneratedProductFeatureModule] extends [never]\n ? FeatureModule\n : GeneratedProductFeatureModule;\n`;
|
||||
}
|
||||
|
||||
export function renderContextIndex(entries: readonly FeatureIndexEntry[]): string {
|
||||
if (entries.length === 0) {
|
||||
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([] as const);\n`;
|
||||
}
|
||||
const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));
|
||||
const imports = sorted
|
||||
.map(
|
||||
(entry, index) =>
|
||||
`import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`,
|
||||
)
|
||||
.join("\n");
|
||||
const indexById = new Map(sorted.map((entry, index) => [entry.id, index] as const));
|
||||
const grouped = new Map<string, FeatureIndexEntry[]>();
|
||||
for (const entry of sorted) {
|
||||
const group = grouped.get(entry.contextId) ?? [];
|
||||
group.push(entry);
|
||||
grouped.set(entry.contextId, group);
|
||||
}
|
||||
|
||||
const contexts = [...grouped.entries()]
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([contextId, features]) => {
|
||||
const first = features[0];
|
||||
if (!first) throw new Error(`Context ${contextId} has no features`);
|
||||
for (const feature of features) {
|
||||
if (feature.contextRoutePath !== first.contextRoutePath) {
|
||||
throw new Error(
|
||||
`Context ${contextId} has conflicting route paths: ${first.contextRoutePath}, ${feature.contextRoutePath}`,
|
||||
);
|
||||
}
|
||||
if (feature.contextMaxFeatures !== first.contextMaxFeatures) {
|
||||
throw new Error(
|
||||
`Context ${contextId} has conflicting maxFeatures budgets: ${first.contextMaxFeatures}, ${feature.contextMaxFeatures}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (features.length > first.contextMaxFeatures) {
|
||||
throw new Error(
|
||||
`Context ${contextId} feature cardinality ${features.length} exceeds budget ${first.contextMaxFeatures}`,
|
||||
);
|
||||
}
|
||||
const featureRefs = features
|
||||
.map((feature) => `featureModule${indexById.get(feature.id)}`)
|
||||
.join(", ");
|
||||
const routeImports = features
|
||||
.map(
|
||||
(feature, index) =>
|
||||
` import(${JSON.stringify(`../features/${feature.directory}/context-routes.ts`)})${index < features.length - 1 ? "," : ""}`,
|
||||
)
|
||||
.join("\n");
|
||||
const routeSpreads = features
|
||||
.map((_, index) => ` ...routeModule${index}.FEATURE_CONTEXT_ROUTES,`)
|
||||
.join("\n");
|
||||
const routeBindings = features
|
||||
.map((_, index) => `routeModule${index}`)
|
||||
.join(", ");
|
||||
return ` defineBoundedContextModule({\n id: ${JSON.stringify(contextId)},\n features: Object.freeze([${featureRefs}]),\n budget: Object.freeze({ maxFeatures: ${first.contextMaxFeatures} }),\n route: Object.freeze({\n path: ${JSON.stringify(first.contextRoutePath)},\n async loadRoutes() {\n const [${routeBindings}] = await Promise.all([\n${routeImports}\n ]);\n return Object.freeze([\n${routeSpreads}\n ]);\n },\n }),\n }),`;
|
||||
})
|
||||
.join("\n");
|
||||
|
||||
const featureImports = imports.length > 0 ? `${imports}\n` : "";
|
||||
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport { defineBoundedContextModule } from "../contexts/bounded-context-module.ts";\n${featureImports}\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([\n${contexts}\n] as const);\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Spec §3.2 / §5. Ownership declarations the generator reads. Each boundary
|
||||
* declares only its parent:
|
||||
*
|
||||
* src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
|
||||
* src/contexts/<context>/context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID,
|
||||
* CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES
|
||||
* src/features/<feature>/feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID
|
||||
*
|
||||
* The generated indexes describe exactly one deployable app: the contexts it
|
||||
* owns and the features those contexts own. Features of other apps are never
|
||||
* imported, so global growth elsewhere cannot enter this app's compile or
|
||||
* boot graph.
|
||||
*/
|
||||
export type AppDeclaration = Readonly<{ id: string; maxContexts: number }>;
|
||||
export type ContextDeclaration = Readonly<{
|
||||
id: string;
|
||||
appId: string;
|
||||
routePath: string;
|
||||
maxFeatures: number;
|
||||
}>;
|
||||
export type FeatureDeclaration = Readonly<{
|
||||
id: string;
|
||||
contextId: string;
|
||||
directory: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* Ownership-indexed view of the declarations. The generator only asks for one
|
||||
* app, that app's contexts and those contexts' features, so its work and its
|
||||
* output are local to the selected app.
|
||||
*/
|
||||
export interface TopologyDeclarationSource {
|
||||
appIds(): readonly string[];
|
||||
app(appId: string): AppDeclaration | undefined;
|
||||
contextsOf(appId: string): readonly ContextDeclaration[];
|
||||
featuresOf(contextId: string): readonly FeatureDeclaration[];
|
||||
}
|
||||
|
||||
export type SelectedAppIndexes = Readonly<{
|
||||
app: AppDeclaration;
|
||||
entries: readonly FeatureIndexEntry[];
|
||||
featureIndex: string;
|
||||
contextIndex: string;
|
||||
appIndex: string;
|
||||
}>;
|
||||
|
||||
export function renderAppIndex(app: AppDeclaration): string {
|
||||
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.
|
||||
export const PRODUCT_APP = Object.freeze({
|
||||
id: ${JSON.stringify(app.id)},
|
||||
maxContexts: ${app.maxContexts},
|
||||
} as const);
|
||||
`;
|
||||
}
|
||||
|
||||
export function resolveSelectedApp(
|
||||
source: TopologyDeclarationSource,
|
||||
requested: string | undefined,
|
||||
): string {
|
||||
if (requested) {
|
||||
if (!source.app(requested)) throw new Error(`Unknown deployable app: ${requested}`);
|
||||
return requested;
|
||||
}
|
||||
const ids = source.appIds();
|
||||
if (ids.length !== 1) {
|
||||
throw new Error(
|
||||
`Select a deployable app with --app=<id> or PRODUCT_APP_ID (declared: ${ids.join(", ") || "none"})`,
|
||||
);
|
||||
}
|
||||
return ids[0] as string;
|
||||
}
|
||||
|
||||
/** The production selection: one app -> its direct contexts -> their features. */
|
||||
export function selectAppIndexes(
|
||||
source: TopologyDeclarationSource,
|
||||
appId: string,
|
||||
): SelectedAppIndexes {
|
||||
const app = source.app(appId);
|
||||
if (!app) throw new Error(`Unknown deployable app: ${appId}`);
|
||||
const contexts = [...source.contextsOf(appId)].sort((left, right) =>
|
||||
left.id.localeCompare(right.id),
|
||||
);
|
||||
const entries: FeatureIndexEntry[] = [];
|
||||
let populatedContexts = 0;
|
||||
for (const context of contexts) {
|
||||
const features = source.featuresOf(context.id);
|
||||
if (features.length === 0) continue;
|
||||
populatedContexts += 1;
|
||||
if (features.length > context.maxFeatures) {
|
||||
throw new Error(
|
||||
`Context ${context.id} feature cardinality ${features.length} exceeds budget ${context.maxFeatures}`,
|
||||
);
|
||||
}
|
||||
for (const feature of features) {
|
||||
entries.push({
|
||||
id: feature.id,
|
||||
importPath: `../features/${feature.directory}/feature-module.ts`,
|
||||
directory: feature.directory,
|
||||
contextId: context.id,
|
||||
contextRoutePath: context.routePath,
|
||||
contextMaxFeatures: context.maxFeatures,
|
||||
});
|
||||
}
|
||||
}
|
||||
if (populatedContexts > app.maxContexts) {
|
||||
throw new Error(
|
||||
`App ${app.id} context cardinality ${populatedContexts} exceeds budget ${app.maxContexts}`,
|
||||
);
|
||||
}
|
||||
const ids = entries.map((entry) => entry.id);
|
||||
if (new Set(ids).size !== ids.length) {
|
||||
throw new Error(`Duplicate generated feature ids: ${ids.join(", ")}`);
|
||||
}
|
||||
return Object.freeze({
|
||||
app,
|
||||
entries: Object.freeze(entries),
|
||||
featureIndex: renderFeatureIndex(entries),
|
||||
contextIndex: renderContextIndex(entries),
|
||||
appIndex: renderAppIndex(app),
|
||||
});
|
||||
}
|
||||
|
||||
function requiredLiteral(source: string, name: string, file: string): string {
|
||||
const match = source.match(
|
||||
new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`),
|
||||
);
|
||||
if (!match?.[1]) {
|
||||
throw new Error(`${file} must export a literal ${name}`);
|
||||
}
|
||||
return match[1];
|
||||
}
|
||||
|
||||
function requiredInteger(source: string, name: string, file: string): number {
|
||||
const match = source.match(
|
||||
new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(\\d+)`),
|
||||
);
|
||||
const parsed = match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN;
|
||||
if (!Number.isSafeInteger(parsed) || parsed < 1) {
|
||||
throw new Error(`${file} must export a positive integer ${name}`);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
|
||||
async function readDeclarations(
|
||||
directory: string,
|
||||
fileName: string,
|
||||
): Promise<readonly Readonly<{ directory: string; file: string; source: string }>[]> {
|
||||
const found: { directory: string; file: string; source: string }[] = [];
|
||||
let items;
|
||||
try {
|
||||
items = await readdir(directory, { withFileTypes: true });
|
||||
} catch {
|
||||
return found;
|
||||
}
|
||||
for (const item of items) {
|
||||
if (!item.isDirectory()) continue;
|
||||
const file = resolve(directory, item.name, fileName);
|
||||
try {
|
||||
found.push({ directory: item.name, file, source: await readFile(file, "utf8") });
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
/**
|
||||
* Filesystem declaration source. Declarations are small literal headers, so
|
||||
* reading them is a metadata scan; only the selected app's features are ever
|
||||
* imported by the generated output.
|
||||
*/
|
||||
export async function createFileSystemDeclarationSource(
|
||||
root: string,
|
||||
): Promise<TopologyDeclarationSource> {
|
||||
const apps = new Map<string, AppDeclaration>();
|
||||
for (const declaration of await readDeclarations(resolve(root, "src/apps"), "app-module.ts")) {
|
||||
const id = requiredLiteral(declaration.source, "APP_MODULE_ID", declaration.file);
|
||||
if (apps.has(id)) throw new Error(`Duplicate app id: ${id}`);
|
||||
apps.set(id, {
|
||||
id,
|
||||
maxContexts: requiredInteger(declaration.source, "APP_MAX_CONTEXTS", declaration.file),
|
||||
});
|
||||
}
|
||||
const contextsByApp = new Map<string, ContextDeclaration[]>();
|
||||
const contextIds = new Set<string>();
|
||||
for (const declaration of await readDeclarations(resolve(root, "src/contexts"), "context-module.ts")) {
|
||||
const context: ContextDeclaration = {
|
||||
id: requiredLiteral(declaration.source, "CONTEXT_MODULE_ID", declaration.file),
|
||||
appId: requiredLiteral(declaration.source, "CONTEXT_APP_ID", declaration.file),
|
||||
routePath: requiredLiteral(declaration.source, "CONTEXT_ROUTE_PATH", declaration.file),
|
||||
maxFeatures: requiredInteger(declaration.source, "CONTEXT_MAX_FEATURES", declaration.file),
|
||||
};
|
||||
if (contextIds.has(context.id)) throw new Error(`Duplicate context id: ${context.id}`);
|
||||
if (!apps.has(context.appId)) {
|
||||
throw new Error(`Context ${context.id} belongs to undeclared app ${context.appId}`);
|
||||
}
|
||||
contextIds.add(context.id);
|
||||
const owned = contextsByApp.get(context.appId) ?? [];
|
||||
owned.push(context);
|
||||
contextsByApp.set(context.appId, owned);
|
||||
}
|
||||
const featuresByContext = new Map<string, FeatureDeclaration[]>();
|
||||
const featureIds = new Set<string>();
|
||||
for (const declaration of await readDeclarations(resolve(root, "src/features"), "feature-module.ts")) {
|
||||
const feature: FeatureDeclaration = {
|
||||
id: requiredLiteral(declaration.source, "FEATURE_MODULE_ID", declaration.file),
|
||||
contextId: requiredLiteral(declaration.source, "FEATURE_CONTEXT_ID", declaration.file),
|
||||
directory: declaration.directory,
|
||||
};
|
||||
if (featureIds.has(feature.id)) throw new Error(`Duplicate generated feature ids: ${feature.id}`);
|
||||
if (!contextIds.has(feature.contextId)) {
|
||||
throw new Error(`Feature ${feature.id} belongs to undeclared context ${feature.contextId}`);
|
||||
}
|
||||
featureIds.add(feature.id);
|
||||
const owned = featuresByContext.get(feature.contextId) ?? [];
|
||||
owned.push(feature);
|
||||
featuresByContext.set(feature.contextId, owned);
|
||||
}
|
||||
return Object.freeze({
|
||||
appIds: () => [...apps.keys()].sort(),
|
||||
app: (appId: string) => apps.get(appId),
|
||||
contextsOf: (appId: string) => contextsByApp.get(appId) ?? [],
|
||||
featuresOf: (contextId: string) => featuresByContext.get(contextId) ?? [],
|
||||
});
|
||||
}
|
||||
|
||||
export async function generateAppIndexes(
|
||||
root: string,
|
||||
requestedApp: string | undefined,
|
||||
): Promise<SelectedAppIndexes> {
|
||||
const source = await createFileSystemDeclarationSource(root);
|
||||
return selectAppIndexes(source, resolveSelectedApp(source, requestedApp));
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const scriptDir = dirname(fileURLToPath(import.meta.url));
|
||||
// `--root=` points the same production command at another checkout (used by
|
||||
// the multi-app topology evidence); the default is this repository.
|
||||
const rootArgument = process.argv
|
||||
.find((argument) => argument.startsWith("--root="))
|
||||
?.slice("--root=".length);
|
||||
const root = rootArgument ? resolve(rootArgument) : resolve(scriptDir, "..");
|
||||
const outputRoot = resolve(root, "src/.generated");
|
||||
const outputs = {
|
||||
feature: resolve(outputRoot, "product-feature-index.ts"),
|
||||
context: resolve(outputRoot, "product-context-index.ts"),
|
||||
app: resolve(outputRoot, "product-app.ts"),
|
||||
};
|
||||
const requestedApp =
|
||||
process.argv.find((argument) => argument.startsWith("--app="))?.slice("--app=".length) ||
|
||||
process.env["PRODUCT_APP_ID"] ||
|
||||
undefined;
|
||||
const selected = await generateAppIndexes(root, requestedApp);
|
||||
const rendered = {
|
||||
feature: selected.featureIndex,
|
||||
context: selected.contextIndex,
|
||||
app: selected.appIndex,
|
||||
};
|
||||
await mkdir(outputRoot, { recursive: true });
|
||||
|
||||
if (process.argv.includes("--check")) {
|
||||
const stale: string[] = [];
|
||||
for (const key of ["feature", "context", "app"] as const) {
|
||||
const current = await readFile(outputs[key], "utf8").catch(() => "");
|
||||
if (current !== rendered[key]) stale.push(relative(root, outputs[key]));
|
||||
}
|
||||
if (stale.length > 0) {
|
||||
throw new Error(`Generated topology index is stale: ${stale.join(", ")}`);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
await Promise.all(
|
||||
(["feature", "context", "app"] as const).map((key) =>
|
||||
writeFile(outputs[key], rendered[key], "utf8"),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
import { readFile, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import process from "node:process";
|
||||
|
||||
import {
|
||||
DEPLOYMENT_TARGETS,
|
||||
isDeploymentTarget,
|
||||
type DeploymentTarget,
|
||||
} from "../src/contracts/deployment-admission.ts";
|
||||
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
|
||||
|
||||
/**
|
||||
* §6.4. Materializes `dist/config.json` from the profile the build declares.
|
||||
*
|
||||
* `public/` is copied verbatim into `dist/`, so before this step the runtime
|
||||
* document that shipped with every build was the local one — `APP_ENV: local`,
|
||||
* `AUTH_MODE: demo`, a loopback API — regardless of what the build was for.
|
||||
* The profile is the source of truth instead, and the only values a deployment
|
||||
* may inject are the ones it actually owns: its endpoints and its identity.
|
||||
*
|
||||
* The result is validated against the same V2 schema the browser will apply, so
|
||||
* an override cannot produce a document that only fails at boot.
|
||||
*/
|
||||
|
||||
const PROFILE_DIRECTORY = "config/runtime";
|
||||
const OUTPUT_PATH = "dist/config.json";
|
||||
|
||||
/**
|
||||
* Deployment-supplied values. Everything else is fixed by the profile so a
|
||||
* deployment cannot quietly widen what was reviewed.
|
||||
*/
|
||||
const OVERRIDES = Object.freeze({
|
||||
API_BASE_URL: "RUNTIME_API_BASE_URL",
|
||||
TELEMETRY_ENDPOINT: "RUNTIME_TELEMETRY_ENDPOINT",
|
||||
} as const);
|
||||
|
||||
export async function generateRuntimeConfig(
|
||||
target: DeploymentTarget,
|
||||
environment: NodeJS.ProcessEnv = process.env,
|
||||
): Promise<Record<string, unknown>> {
|
||||
const profilePath = path.join(PROFILE_DIRECTORY, `${target}.json`);
|
||||
const source: unknown = JSON.parse(await readFile(profilePath, "utf8"));
|
||||
if (source === null || typeof source !== "object" || Array.isArray(source)) {
|
||||
throw new TypeError(`${profilePath}: runtime profile must be an object`);
|
||||
}
|
||||
const draft: Record<string, unknown> = { ...(source as Record<string, unknown>) };
|
||||
if (draft["APP_ENV"] !== target) {
|
||||
throw new Error(
|
||||
`${profilePath}: declares APP_ENV ${String(draft["APP_ENV"])}, expected ${target}`,
|
||||
);
|
||||
}
|
||||
for (const [field, variable] of Object.entries(OVERRIDES)) {
|
||||
const supplied = environment[variable];
|
||||
if (supplied !== undefined && supplied !== "") draft[field] = supplied;
|
||||
}
|
||||
const buildId = environment["VITE_BUILD_ID"] ?? "local-build";
|
||||
const releaseId = environment["RELEASE_ID"] ?? "local-release";
|
||||
draft["BUILD_ID"] = buildId;
|
||||
draft["RELEASE_ID"] = releaseId;
|
||||
|
||||
const parsed = runtimeConfigV2ArtifactSchema.safeParse(draft);
|
||||
if (!parsed.success) {
|
||||
const issues = parsed.error.issues
|
||||
.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
|
||||
.join("\n ");
|
||||
throw new Error(`${profilePath}: runtime config is invalid\n ${issues}`);
|
||||
}
|
||||
return draft;
|
||||
}
|
||||
|
||||
function resolveTarget(environment: NodeJS.ProcessEnv): DeploymentTarget {
|
||||
const declared = environment["APP_PROFILE"] ?? "local";
|
||||
if (!isDeploymentTarget(declared)) {
|
||||
throw new Error(
|
||||
`APP_PROFILE must be one of ${DEPLOYMENT_TARGETS.join(", ")}; received ${declared}`,
|
||||
);
|
||||
}
|
||||
return declared;
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const target = resolveTarget(process.env);
|
||||
const config = await generateRuntimeConfig(target);
|
||||
await writeFile(OUTPUT_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
|
||||
process.stdout.write(
|
||||
`runtime config: ${target} profile written to ${OUTPUT_PATH} ` +
|
||||
`(APP_ENV=${String(config["APP_ENV"])}, AUTH_MODE=${String(config["AUTH_MODE"])})\n`,
|
||||
);
|
||||
}
|
||||
|
||||
if (process.argv[1] && import.meta.url.endsWith(path.basename(process.argv[1]))) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import {
|
||||
CACHEABLE_ASSET_CONTENT_TYPES,
|
||||
canonicalStaticManifestBytes,
|
||||
decodeStaticAssetManifest,
|
||||
isCanonicalStaticAssetUrl,
|
||||
} from "../src/contracts/service-worker-static-manifest.ts";
|
||||
import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
SERVICE_WORKER_BOUNDS,
|
||||
SERVICE_WORKER_SCRIPT_PATH,
|
||||
type StaticAssetManifestV1,
|
||||
} from "../src/contracts/service-worker.ts";
|
||||
|
||||
/**
|
||||
* §17.2.2 step 4. Scans the completed app `dist` and emits the exact hashed
|
||||
* asset list the Service Worker will verify at install time.
|
||||
*
|
||||
* `service-worker.js` itself and `index.html` are excluded (§17.2.2), as are
|
||||
* the runtime config and release manifest, which are network-only (§18.4).
|
||||
*/
|
||||
|
||||
const OUTPUT = ".generated/frontend-runtime/service-worker-assets.ts";
|
||||
|
||||
// SW-RR-03. The generator and the shared decoder read the same table, so a
|
||||
// manifest this script produces can never be one the runtime contract refuses.
|
||||
const CACHEABLE_EXTENSIONS = CACHEABLE_ASSET_CONTENT_TYPES;
|
||||
|
||||
const EXCLUDED_FILES: ReadonlySet<string> = new Set([
|
||||
"index.html",
|
||||
SERVICE_WORKER_SCRIPT_PATH,
|
||||
"config.json",
|
||||
"release-manifest.json",
|
||||
"runtime-config.schema.json",
|
||||
]);
|
||||
|
||||
/** Vite emits content-hashed names; only those may be treated as immutable. */
|
||||
const HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/;
|
||||
|
||||
export async function collectStaticAssets(
|
||||
distDirectory: string,
|
||||
buildId: string,
|
||||
releaseId: string,
|
||||
): Promise<StaticAssetManifestV1> {
|
||||
const files = await walk(distDirectory, distDirectory);
|
||||
const assets: StaticAssetManifestV1["assets"][number][] = [];
|
||||
|
||||
for (const relative of files.sort()) {
|
||||
const base = path.basename(relative);
|
||||
if (EXCLUDED_FILES.has(base) || relative.startsWith(".vite/")) continue;
|
||||
const contentType = CACHEABLE_EXTENSIONS[path.extname(base).toLowerCase()];
|
||||
if (!contentType || !HASHED_NAME.test(base)) continue;
|
||||
|
||||
const absolute = path.join(distDirectory, relative);
|
||||
const bytes = await readFile(absolute);
|
||||
if (bytes.byteLength > SERVICE_WORKER_BOUNDS.singleAssetBytes) {
|
||||
throw new Error(`Static asset exceeds its byte bound: ${relative}`);
|
||||
}
|
||||
// SW-02. The URL is checked against the same predicate the runtime decoder
|
||||
// applies. Emitting a path the decoder will refuse turned a correct build
|
||||
// into a runtime contract failure discovered only at install time.
|
||||
const url = `/${relative.split(path.sep).join("/")}`;
|
||||
if (!isCanonicalStaticAssetUrl(url)) {
|
||||
throw new Error(
|
||||
`Static asset path is not canonical for the service worker manifest: ${relative}`,
|
||||
);
|
||||
}
|
||||
assets.push({
|
||||
url,
|
||||
sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
|
||||
bytes: bytes.byteLength,
|
||||
contentType,
|
||||
});
|
||||
}
|
||||
|
||||
if (assets.length > SERVICE_WORKER_BOUNDS.assets) {
|
||||
throw new Error("Static asset count exceeds its bound.");
|
||||
}
|
||||
const totalBytes = assets.reduce((sum, asset) => sum + asset.bytes, 0);
|
||||
if (totalBytes > SERVICE_WORKER_BOUNDS.assetSetBytes) {
|
||||
throw new Error("Static asset set exceeds its byte bound.");
|
||||
}
|
||||
|
||||
// SW-05. The canonical byte serialization lives in the shared runtime-neutral
|
||||
// codec so the worker can recompute the identical digest with WebCrypto.
|
||||
const setDigest: `sha256:${string}` = `sha256:${createHash("sha256")
|
||||
.update(canonicalStaticManifestBytes(assets))
|
||||
.digest("hex")}`;
|
||||
|
||||
const manifest: StaticAssetManifestV1 = {
|
||||
schemaVersion: 1,
|
||||
buildId,
|
||||
releaseId,
|
||||
setDigest,
|
||||
assets,
|
||||
};
|
||||
// SW-02. Every manifest this generator returns has already passed the exact
|
||||
// decoder the runtime will apply to it, so the build stops here rather than
|
||||
// at install time.
|
||||
const decoded = decodeStaticAssetManifest(manifest);
|
||||
if (!decoded.ok) {
|
||||
throw new Error(
|
||||
`Generated service worker manifest is not decodable: ${decoded.error.reason}`,
|
||||
);
|
||||
}
|
||||
return manifest;
|
||||
}
|
||||
|
||||
|
||||
async function walk(root: string, current: string): Promise<string[]> {
|
||||
const entries = await readdir(current, { withFileTypes: true });
|
||||
const files: string[] = [];
|
||||
for (const entry of entries) {
|
||||
const absolute = path.join(current, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
files.push(...(await walk(root, absolute)));
|
||||
} else if ((await stat(absolute)).isFile()) {
|
||||
files.push(path.relative(root, absolute));
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const distDirectory = process.argv[2] ?? "dist";
|
||||
const buildId = process.env.VITE_BUILD_ID ?? "local-build";
|
||||
const releaseId = process.env.RELEASE_ID ?? "local-release";
|
||||
const manifest = await collectStaticAssets(distDirectory, buildId, releaseId);
|
||||
const source = [
|
||||
"// Generated by scripts/generate-service-worker-assets.ts. Do not edit.",
|
||||
"",
|
||||
'import type { StaticAssetManifestV1 } from "../../src/contracts/service-worker.ts";',
|
||||
"",
|
||||
`export const SERVICE_WORKER_ASSETS: StaticAssetManifestV1 = ${JSON.stringify(
|
||||
manifest,
|
||||
null,
|
||||
2,
|
||||
)} as const;`,
|
||||
"",
|
||||
].join("\n");
|
||||
await mkdir(path.dirname(OUTPUT), { recursive: true });
|
||||
await writeFile(OUTPUT, source, "utf8");
|
||||
process.stdout.write(
|
||||
`service worker assets: ${manifest.assets.length} file(s) ${manifest.setDigest}\n`,
|
||||
);
|
||||
}
|
||||
|
||||
if (process.argv[1]?.endsWith("generate-service-worker-assets.ts")) {
|
||||
await main();
|
||||
}
|
||||
@@ -0,0 +1,382 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
mkdir,
|
||||
readFile,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
|
||||
import {
|
||||
bundleOutputInventoryArtifactSchema,
|
||||
buildManifestArtifactSchema,
|
||||
dependencyDiffArtifactSchema,
|
||||
dependencyInventoryArtifactSchema,
|
||||
licenseReportArtifactSchema,
|
||||
provenanceArtifactSchema,
|
||||
sbomArtifactSchema,
|
||||
supplyChainVerificationArtifactSchema,
|
||||
vulnerabilityReportArtifactSchema,
|
||||
} from "./contracts/release-artifacts.ts";
|
||||
import {
|
||||
flattenPnpmDependencyTree,
|
||||
isValidSha512Integrity,
|
||||
parsePnpmLockfilePackages,
|
||||
PROJECT_NAME,
|
||||
supplyChainDigest,
|
||||
verifySupplyChainCoherence,
|
||||
} from "./lib/supply-chain.ts";
|
||||
import {
|
||||
createLocalVulnerabilityReport,
|
||||
distChecksumsText,
|
||||
LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS,
|
||||
recomputeDependencyEvidence,
|
||||
recomputeLicenseEvidence,
|
||||
} from "./lib/local-policy-evidence.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
import { digestReleaseInputFiles } from "./lib/release-input-evidence.ts";
|
||||
import {
|
||||
buildRepositoryFileInventory,
|
||||
parseRepositoryFileInventoryPolicy,
|
||||
} from "./lib/repository-file-inventory.ts";
|
||||
import { collectDistOutputs, distSha256 } from "./lib/release-candidate.ts";
|
||||
import { deterministicSupplyChainGeneratedAt } from "./lib/supply-chain-time.ts";
|
||||
|
||||
type Document = Record<string, unknown>;
|
||||
|
||||
function isRecord(value: unknown): value is Document {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function documentValue(value: unknown, label: string): Document {
|
||||
if (!isRecord(value)) throw new Error(`${label} must be a JSON object`);
|
||||
return value;
|
||||
}
|
||||
|
||||
function stringMap(value: unknown): Record<string, string> {
|
||||
if (!isRecord(value)) return {};
|
||||
return Object.fromEntries(
|
||||
Object.entries(value).filter(
|
||||
(entry): entry is [string, string] => typeof entry[1] === "string",
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
async function jsonDocument(file: string): Promise<Document> {
|
||||
const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
|
||||
return documentValue(parsed, file);
|
||||
}
|
||||
|
||||
async function sha256File(file: string): Promise<string> {
|
||||
return createHash("sha256").update(await readFile(file)).digest("hex");
|
||||
}
|
||||
|
||||
async function optionalJson(file: string): Promise<Document | null> {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
|
||||
return isRecord(parsed) ? parsed : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export async function buildDependencyInventory() {
|
||||
const packageJson = await jsonDocument("package.json");
|
||||
const lockfileText = await readFile("pnpm-lock.yaml", "utf8");
|
||||
const lockfileSha256 = createHash("sha256")
|
||||
.update(lockfileText)
|
||||
.digest("hex");
|
||||
const listed = spawnSync(
|
||||
"corepack",
|
||||
["pnpm", "list", "--json", "--depth", "Infinity"],
|
||||
{
|
||||
encoding: "utf8",
|
||||
maxBuffer: 32 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
if (listed.status !== 0) {
|
||||
throw new Error(`pnpm dependency graph failed: ${listed.stderr}`);
|
||||
}
|
||||
const roots: unknown = JSON.parse(listed.stdout);
|
||||
const root = Array.isArray(roots) && isRecord(roots[0]) ? roots[0] : null;
|
||||
if (!root) throw new Error("pnpm dependency graph root is invalid");
|
||||
const flattened = await flattenPnpmDependencyTree(
|
||||
root,
|
||||
stringMap(packageJson.dependencies),
|
||||
stringMap(packageJson.devDependencies),
|
||||
);
|
||||
const lockRows = parsePnpmLockfilePackages(lockfileText);
|
||||
const lockByIdentity = new Map(
|
||||
lockRows.map((row) => [`${row.name}@${row.version}`, row]),
|
||||
);
|
||||
const failures: string[] = [];
|
||||
const dependencies = flattened.map((dependency) => {
|
||||
const identity = `${dependency.name}@${dependency.version}`;
|
||||
const lockRow = lockByIdentity.get(identity);
|
||||
if (!lockRow) failures.push(`dependency missing from lockfile: ${identity}`);
|
||||
if (lockRow && !isValidSha512Integrity(lockRow.integrity)) {
|
||||
failures.push(`dependency has invalid sha512 integrity: ${identity}`);
|
||||
}
|
||||
return {
|
||||
...dependency,
|
||||
integrity: lockRow?.integrity ?? "missing",
|
||||
};
|
||||
});
|
||||
const inventoryIds = new Set(
|
||||
dependencies.map((dependency) => `${dependency.name}@${dependency.version}`),
|
||||
);
|
||||
for (const lockRow of lockRows) {
|
||||
const identity = `${lockRow.name}@${lockRow.version}`;
|
||||
if (!inventoryIds.has(identity)) {
|
||||
failures.push(`transitive lockfile dependency omitted: ${identity}`);
|
||||
}
|
||||
}
|
||||
if (failures.length > 0) {
|
||||
throw new Error(failures.join("\n"));
|
||||
}
|
||||
return {
|
||||
schemaVersion: 2,
|
||||
packageManager: String(packageJson.packageManager ?? ""),
|
||||
lockfileSha256,
|
||||
dependencyCount: dependencies.length,
|
||||
directDependencyCount: dependencies.filter((entry) => entry.direct).length,
|
||||
dependencies,
|
||||
};
|
||||
}
|
||||
|
||||
const packageJson = await jsonDocument("package.json");
|
||||
const buildManifest = buildManifestArtifactSchema.parse(
|
||||
await jsonDocument("artifacts/release/build-manifest.json"),
|
||||
);
|
||||
const secretScanPolicy = documentValue(
|
||||
JSON.parse(await readFile("config/security/secret-scan-policy.json", "utf8")),
|
||||
"secret scan policy",
|
||||
);
|
||||
const inventoryPolicy = parseRepositoryFileInventoryPolicy(secretScanPolicy);
|
||||
const repositoryInventory = await buildRepositoryFileInventory({
|
||||
trackedRoots: inventoryPolicy.trackedRoots,
|
||||
generatedRoots: inventoryPolicy.generatedRoots,
|
||||
optionalRoots: inventoryPolicy.optionalRoots,
|
||||
});
|
||||
const outputs = await collectDistOutputs();
|
||||
const distDigest = distSha256(outputs);
|
||||
const inventory = await buildDependencyInventory();
|
||||
const licensePolicy = JSON.parse(
|
||||
await readFile("config/security/dependency-policy.json", "utf8"),
|
||||
);
|
||||
|
||||
const baseline = await optionalJson(
|
||||
"config/security/dependency-baseline.json",
|
||||
);
|
||||
const baselineApproval = await optionalJson(
|
||||
"config/security/dependency-baseline.approval.json",
|
||||
);
|
||||
const dependencyEvidence = JSON.parse(
|
||||
await readFile(
|
||||
"config/security/dependency-change-evidence.json",
|
||||
"utf8",
|
||||
),
|
||||
);
|
||||
const skipsBaseline = process.argv.includes("--no-baseline");
|
||||
const dependencyPolicy = recomputeDependencyEvidence({
|
||||
inventory,
|
||||
baseline,
|
||||
baselineApproval,
|
||||
dependencyChangeEvidence: dependencyEvidence,
|
||||
skipBaseline: skipsBaseline,
|
||||
});
|
||||
const licenseEvidence = recomputeLicenseEvidence({
|
||||
inventory,
|
||||
policy: licensePolicy,
|
||||
});
|
||||
|
||||
const vulnerabilityReport = createLocalVulnerabilityReport(
|
||||
inventory.lockfileSha256,
|
||||
);
|
||||
|
||||
const sourceFiles = [...repositoryInventory.trackedFiles];
|
||||
const sourceSetSha256 = await digestReleaseInputFiles(sourceFiles);
|
||||
|
||||
const components = inventory.dependencies.map((dependency) => ({
|
||||
type: "library",
|
||||
"bom-ref": `pkg:npm/${encodeURIComponent(dependency.name)}@${dependency.version}`,
|
||||
name: dependency.name,
|
||||
version: dependency.version,
|
||||
scope: dependency.optional ? "optional" : "required",
|
||||
hashes: [
|
||||
{
|
||||
alg: "SHA-512",
|
||||
content: dependency.integrity.slice("sha512-".length),
|
||||
},
|
||||
],
|
||||
licenses:
|
||||
dependency.license === "NOASSERTION"
|
||||
? [{ expression: "NOASSERTION" }]
|
||||
: [{ expression: dependency.license }],
|
||||
properties: [
|
||||
{ name: "ca:direct", value: String(dependency.direct) },
|
||||
{ name: "ca:scope", value: dependency.scope },
|
||||
],
|
||||
}));
|
||||
const serialSeed = supplyChainDigest({
|
||||
lockfileSha256: inventory.lockfileSha256,
|
||||
components: components.map((component) => component["bom-ref"]),
|
||||
});
|
||||
const sbom = {
|
||||
bomFormat: "CycloneDX",
|
||||
specVersion: "1.6",
|
||||
serialNumber: `urn:uuid:${serialSeed.slice(0, 8)}-${serialSeed.slice(8, 12)}-${serialSeed.slice(12, 16)}-${serialSeed.slice(16, 20)}-${serialSeed.slice(20, 32)}`,
|
||||
version: 1,
|
||||
metadata: {
|
||||
component: {
|
||||
type: "application",
|
||||
name: String(packageJson.name ?? ""),
|
||||
version: String(packageJson.version ?? ""),
|
||||
},
|
||||
properties: [
|
||||
{
|
||||
name: "ca:lockfileSha256",
|
||||
value: inventory.lockfileSha256,
|
||||
},
|
||||
],
|
||||
},
|
||||
components,
|
||||
dependencies: inventory.dependencies.map((dependency) => ({
|
||||
ref: `pkg:npm/${encodeURIComponent(dependency.name)}@${dependency.version}`,
|
||||
dependsOn: dependency.dependencies.map((identity) => {
|
||||
const separator = identity.lastIndexOf("@");
|
||||
return `pkg:npm/${encodeURIComponent(identity.slice(0, separator))}@${identity.slice(separator + 1)}`;
|
||||
}),
|
||||
})),
|
||||
};
|
||||
|
||||
const provenance = {
|
||||
_type: "https://in-toto.io/Statement/v1",
|
||||
subject: [{ name: "dist", digest: { sha256: distDigest } }],
|
||||
predicateType: "https://slsa.dev/provenance/v1",
|
||||
predicate: {
|
||||
buildDefinition: {
|
||||
buildType: "https://vite.dev/build/v1",
|
||||
externalParameters: {
|
||||
nodeVersion: process.version,
|
||||
packageManager: String(packageJson.packageManager ?? ""),
|
||||
},
|
||||
internalParameters: {
|
||||
sourceSetSha256,
|
||||
},
|
||||
resolvedDependencies: [
|
||||
{
|
||||
uri: "pnpm-lock.yaml",
|
||||
digest: { sha256: inventory.lockfileSha256 },
|
||||
},
|
||||
],
|
||||
},
|
||||
runDetails: {
|
||||
builder: { id: `local:${PROJECT_NAME}` },
|
||||
metadata: { invocationId: "LOCAL_UNSIGNED" },
|
||||
},
|
||||
materials: {
|
||||
lockfileSha256: inventory.lockfileSha256,
|
||||
sourceSetSha256,
|
||||
sbomSha256: supplyChainDigest(sbom),
|
||||
},
|
||||
},
|
||||
};
|
||||
const coherence = verifySupplyChainCoherence(
|
||||
sbom,
|
||||
inventory,
|
||||
provenance,
|
||||
distDigest,
|
||||
);
|
||||
|
||||
const localFailures = [
|
||||
...licenseEvidence.failures,
|
||||
...dependencyPolicy.failures,
|
||||
...coherence.failures,
|
||||
];
|
||||
const localPassed = localFailures.length === 0;
|
||||
const verification = {
|
||||
schemaVersion: 1,
|
||||
localStatus: localPassed ? "PASS" : "FAIL",
|
||||
...LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS,
|
||||
lockfileSha256: inventory.lockfileSha256,
|
||||
sourceSetSha256,
|
||||
distSha256: distDigest,
|
||||
sbomSha256: supplyChainDigest(sbom),
|
||||
dependencyDiff: dependencyPolicy.dependencyDiff,
|
||||
highRiskReview: dependencyPolicy.highRisk,
|
||||
failures: localFailures,
|
||||
};
|
||||
const bundleReport = {
|
||||
schemaVersion: 1,
|
||||
generatedAt: deterministicSupplyChainGeneratedAt({
|
||||
generatedAt: buildManifest.generatedAt,
|
||||
sourceDateEpoch: buildManifest.buildContext.sourceDateEpoch,
|
||||
}),
|
||||
context: {
|
||||
nodeVersion: process.version,
|
||||
packageManager: String(packageJson.packageManager ?? ""),
|
||||
runnerImage:
|
||||
process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`,
|
||||
},
|
||||
outputs,
|
||||
};
|
||||
const dependencyDiffReport = dependencyPolicy.report;
|
||||
const licenseReport = licenseEvidence.report;
|
||||
|
||||
await mkdir("artifacts/performance", { recursive: true });
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await mkdir("artifacts/security", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/performance/bundle.json",
|
||||
schema: bundleOutputInventoryArtifactSchema,
|
||||
value: bundleReport,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/dependency-inventory.json",
|
||||
schema: dependencyInventoryArtifactSchema,
|
||||
value: inventory,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/sbom.cdx.json",
|
||||
schema: sbomArtifactSchema,
|
||||
value: sbom,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/provenance.json",
|
||||
schema: provenanceArtifactSchema,
|
||||
value: provenance,
|
||||
});
|
||||
await writeFile(
|
||||
"artifacts/release/checksums.txt",
|
||||
distChecksumsText(outputs),
|
||||
);
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/security/dependency-diff.json",
|
||||
schema: dependencyDiffArtifactSchema,
|
||||
value: dependencyDiffReport,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/security/license-report.json",
|
||||
schema: licenseReportArtifactSchema,
|
||||
value: licenseReport,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/security/vulnerability-report.json",
|
||||
schema: vulnerabilityReportArtifactSchema,
|
||||
value: vulnerabilityReport,
|
||||
});
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/security/supply-chain-verification.json",
|
||||
schema: supplyChainVerificationArtifactSchema,
|
||||
value: verification,
|
||||
});
|
||||
|
||||
if (!localPassed) {
|
||||
process.stderr.write(
|
||||
`Local supply-chain verification failed:\n- ${localFailures.join("\n- ")}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Supply chain: LOCAL PASS (${inventory.dependencyCount} dependencies); promotion=${verification.promotionStatus}\n`,
|
||||
);
|
||||
@@ -0,0 +1,66 @@
|
||||
import type { SpawnSyncOptionsWithStringEncoding } from "node:child_process";
|
||||
|
||||
export const PNPM_SCRIPT_TIMEOUT_MS = 60_000;
|
||||
export const PNPM_SCRIPT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
|
||||
|
||||
type BoundedChildInvocation = Readonly<{
|
||||
command: string;
|
||||
arguments: readonly string[];
|
||||
options: SpawnSyncOptionsWithStringEncoding;
|
||||
}>;
|
||||
|
||||
type PnpmScriptResult = Readonly<{
|
||||
status: number | null;
|
||||
signal: NodeJS.Signals | null;
|
||||
error?: Error;
|
||||
}>;
|
||||
|
||||
export function createBoundedPnpmScriptInvocation(input: Readonly<{
|
||||
nodePath: string;
|
||||
pnpmCli: string;
|
||||
script: string;
|
||||
environment: NodeJS.ProcessEnv;
|
||||
}>): BoundedChildInvocation {
|
||||
return createBoundedChildInvocation({
|
||||
command: input.nodePath,
|
||||
arguments: [input.pnpmCli, "run", input.script],
|
||||
environment: input.environment,
|
||||
});
|
||||
}
|
||||
|
||||
export function createBoundedChildInvocation(input: Readonly<{
|
||||
command: string;
|
||||
arguments: readonly string[];
|
||||
environment: NodeJS.ProcessEnv;
|
||||
cwd?: string;
|
||||
}>): BoundedChildInvocation {
|
||||
return Object.freeze({
|
||||
command: input.command,
|
||||
arguments: Object.freeze([...input.arguments]),
|
||||
options: Object.freeze({
|
||||
...(input.cwd === undefined ? {} : { cwd: input.cwd }),
|
||||
encoding: "utf8",
|
||||
env: input.environment,
|
||||
killSignal: "SIGTERM",
|
||||
maxBuffer: PNPM_SCRIPT_MAX_OUTPUT_BYTES,
|
||||
timeout: PNPM_SCRIPT_TIMEOUT_MS,
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
export function formatPnpmScriptFailure(
|
||||
script: string,
|
||||
result: PnpmScriptResult,
|
||||
): string {
|
||||
const code =
|
||||
result.error && "code" in result.error &&
|
||||
typeof result.error.code === "string"
|
||||
? result.error.code
|
||||
: null;
|
||||
const message = result.error?.message.trim().replace(/\s+/g, " ") ?? null;
|
||||
const error =
|
||||
result.error === undefined
|
||||
? "none"
|
||||
: `${code ?? result.error.name}: ${message || "no message"}`;
|
||||
return `${script} failed: exit=${String(result.status)}, signal=${result.signal ?? "none"}, error=${error}`;
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
export const CI_BUILD_ENVIRONMENT_VARIABLES = Object.freeze([
|
||||
"VITE_BUILD_ID",
|
||||
"VITE_COMMIT_SHA",
|
||||
"RELEASE_ID",
|
||||
"CI_RUNNER_IMAGE",
|
||||
"SOURCE_DATE_EPOCH",
|
||||
]);
|
||||
|
||||
export function ciBuildEnvironmentFailures(
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
) {
|
||||
if (environment.CI !== "true") return [];
|
||||
|
||||
const failures = CI_BUILD_ENVIRONMENT_VARIABLES.filter(
|
||||
(name) => !environment[name]?.trim(),
|
||||
).map((name) => `missing required CI build environment: ${name}`);
|
||||
|
||||
const commitSha = environment.VITE_COMMIT_SHA?.trim();
|
||||
if (commitSha && !isValidCommitSha(commitSha)) {
|
||||
failures.push(
|
||||
"VITE_COMMIT_SHA must be a full 40- or 64-character hexadecimal commit ID",
|
||||
);
|
||||
}
|
||||
|
||||
const sourceDateEpoch = environment.SOURCE_DATE_EPOCH?.trim();
|
||||
if (sourceDateEpoch && !isValidSourceDateEpoch(sourceDateEpoch)) {
|
||||
failures.push("SOURCE_DATE_EPOCH must be non-negative epoch seconds");
|
||||
}
|
||||
|
||||
const runnerImage = environment.CI_RUNNER_IMAGE?.trim();
|
||||
if (
|
||||
runnerImage &&
|
||||
!/@sha256:[0-9a-f]{64}$/i.test(runnerImage)
|
||||
) {
|
||||
failures.push(
|
||||
"CI_RUNNER_IMAGE must end with an immutable @sha256 image digest",
|
||||
);
|
||||
}
|
||||
|
||||
return failures;
|
||||
}
|
||||
|
||||
export function assertCiBuildEnvironment(
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
) {
|
||||
const failures = ciBuildEnvironmentFailures(environment);
|
||||
if (failures.length > 0) {
|
||||
throw new Error(failures.join("; "));
|
||||
}
|
||||
}
|
||||
|
||||
export function isValidCommitSha(value: string) {
|
||||
return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
|
||||
}
|
||||
|
||||
export function isValidSourceDateEpoch(value: string) {
|
||||
if (!/^\d+$/.test(value)) return false;
|
||||
const milliseconds = Number(value) * 1_000;
|
||||
return Number.isSafeInteger(milliseconds) && Number.isFinite(
|
||||
new Date(milliseconds).getTime(),
|
||||
);
|
||||
}
|
||||
|
||||
export function ciCheckoutIdentityFailures(
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
checkout: { commitSha: string; sourceDateEpoch: string },
|
||||
) {
|
||||
if (environment.CI !== "true") return [];
|
||||
|
||||
const failures = [];
|
||||
const configuredCommitSha = environment.VITE_COMMIT_SHA?.trim();
|
||||
if (
|
||||
configuredCommitSha &&
|
||||
configuredCommitSha.toLowerCase() !== checkout.commitSha.toLowerCase()
|
||||
) {
|
||||
failures.push("VITE_COMMIT_SHA does not identify the checked-out commit");
|
||||
}
|
||||
const configuredEpoch = environment.SOURCE_DATE_EPOCH?.trim();
|
||||
if (configuredEpoch && configuredEpoch !== checkout.sourceDateEpoch) {
|
||||
failures.push(
|
||||
"SOURCE_DATE_EPOCH does not match the checked-out commit timestamp",
|
||||
);
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
export function buildDate(
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
) {
|
||||
const sourceDateEpoch = environment.SOURCE_DATE_EPOCH?.trim();
|
||||
if (!sourceDateEpoch) return new Date();
|
||||
if (!isValidSourceDateEpoch(sourceDateEpoch)) {
|
||||
throw new Error("SOURCE_DATE_EPOCH must be non-negative epoch seconds");
|
||||
}
|
||||
return new Date(Number(sourceDateEpoch) * 1_000);
|
||||
}
|
||||
@@ -0,0 +1,188 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { lstat, readFile, realpath } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import type { BuildManifestArtifact } from "../../src/contracts/release-artifacts.ts";
|
||||
import { moduleInventoryArtifactSchema } from "../contracts/release-artifacts.ts";
|
||||
|
||||
type VerifyBuildManifestOutputsDependencies = Readonly<{
|
||||
repositoryRoot?: string;
|
||||
readBytes?: (target: string) => Promise<Buffer>;
|
||||
realpathPath?: (target: string) => Promise<string>;
|
||||
assertRegularFile?: (target: string) => Promise<void>;
|
||||
assertDirectory?: (target: string) => Promise<void>;
|
||||
}>;
|
||||
|
||||
export const CANONICAL_VITE_MANIFEST_PATH = "dist/.vite/manifest.json";
|
||||
|
||||
function isSafeRelativePath(value: string): boolean {
|
||||
return (
|
||||
value.length > 0 &&
|
||||
!path.posix.isAbsolute(value) &&
|
||||
!path.win32.isAbsolute(value) &&
|
||||
!value.includes("\\") &&
|
||||
!value.includes("\0") &&
|
||||
path.posix.normalize(value) === value &&
|
||||
value !== ".." &&
|
||||
!value.startsWith("../")
|
||||
);
|
||||
}
|
||||
|
||||
function isWithinRoot(root: string, target: string): boolean {
|
||||
const relative = path.relative(root, target);
|
||||
return (
|
||||
relative === "" ||
|
||||
(relative !== ".." &&
|
||||
!relative.startsWith(`..${path.sep}`) &&
|
||||
!path.isAbsolute(relative))
|
||||
);
|
||||
}
|
||||
|
||||
function belongsToApprovedRoot(value: string, approvedRoot: string): boolean {
|
||||
return value.startsWith(`${approvedRoot}/`);
|
||||
}
|
||||
|
||||
async function defaultAssertRegularFile(target: string): Promise<void> {
|
||||
const metadata = await lstat(target);
|
||||
if (!metadata.isFile() || metadata.isSymbolicLink()) {
|
||||
throw new TypeError("not a regular file");
|
||||
}
|
||||
}
|
||||
|
||||
async function defaultAssertDirectory(target: string): Promise<void> {
|
||||
const metadata = await lstat(target);
|
||||
if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
|
||||
throw new TypeError("not a directory");
|
||||
}
|
||||
}
|
||||
|
||||
export async function verifyBuildManifestOutputs(
|
||||
manifest: BuildManifestArtifact,
|
||||
dependencies: VerifyBuildManifestOutputsDependencies = {},
|
||||
): Promise<string[]> {
|
||||
const repositoryRoot = path.resolve(dependencies.repositoryRoot ?? process.cwd());
|
||||
const readBytes = dependencies.readBytes ?? readFile;
|
||||
const realpathPath = dependencies.realpathPath ?? realpath;
|
||||
const assertRegularFile = dependencies.assertRegularFile ?? defaultAssertRegularFile;
|
||||
const assertDirectory = dependencies.assertDirectory ?? defaultAssertDirectory;
|
||||
const mismatches: string[] = [];
|
||||
const resolvedRoot = await realpathPath(repositoryRoot);
|
||||
const approvedRoots = new Map<string, Promise<string | null>>();
|
||||
|
||||
function resolveApprovedRoot(relativeRoot: string): Promise<string | null> {
|
||||
const existing = approvedRoots.get(relativeRoot);
|
||||
if (existing) return existing;
|
||||
const pending = (async () => {
|
||||
const absoluteRoot = path.resolve(repositoryRoot, relativeRoot);
|
||||
try {
|
||||
await assertDirectory(absoluteRoot);
|
||||
const resolvedApprovedRoot = await realpathPath(absoluteRoot);
|
||||
return isWithinRoot(resolvedRoot, resolvedApprovedRoot)
|
||||
? resolvedApprovedRoot
|
||||
: null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
})();
|
||||
approvedRoots.set(relativeRoot, pending);
|
||||
return pending;
|
||||
}
|
||||
|
||||
async function confinedPath(
|
||||
label: string,
|
||||
relativePath: string,
|
||||
kind: "file" | "directory",
|
||||
approvedRoot?: string,
|
||||
): Promise<string | null> {
|
||||
if (
|
||||
!isSafeRelativePath(relativePath) ||
|
||||
(approvedRoot !== undefined &&
|
||||
!belongsToApprovedRoot(relativePath, approvedRoot))
|
||||
) {
|
||||
mismatches.push(`buildManifest:${label}:path`);
|
||||
return null;
|
||||
}
|
||||
const absolutePath = path.resolve(repositoryRoot, relativePath);
|
||||
if (!isWithinRoot(repositoryRoot, absolutePath)) {
|
||||
mismatches.push(`buildManifest:${label}:path`);
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
if (kind === "file") await assertRegularFile(absolutePath);
|
||||
else await assertDirectory(absolutePath);
|
||||
const resolvedPath = await realpathPath(absolutePath);
|
||||
const resolvedApprovedRoot = approvedRoot
|
||||
? await resolveApprovedRoot(approvedRoot)
|
||||
: resolvedRoot;
|
||||
if (
|
||||
resolvedApprovedRoot === null ||
|
||||
!isWithinRoot(resolvedRoot, resolvedPath) ||
|
||||
!isWithinRoot(resolvedApprovedRoot, resolvedPath)
|
||||
) {
|
||||
mismatches.push(`buildManifest:${label}:path`);
|
||||
return null;
|
||||
}
|
||||
return absolutePath;
|
||||
} catch {
|
||||
mismatches.push(`buildManifest:${label}:missing`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
if (manifest.outputs.directory !== "dist") {
|
||||
mismatches.push("buildManifest:directory:path");
|
||||
} else {
|
||||
await confinedPath("directory", manifest.outputs.directory, "directory");
|
||||
}
|
||||
if (manifest.outputs.viteManifest !== CANONICAL_VITE_MANIFEST_PATH) {
|
||||
mismatches.push("buildManifest:viteManifest:path");
|
||||
} else {
|
||||
await confinedPath(
|
||||
"viteManifest",
|
||||
manifest.outputs.viteManifest,
|
||||
"file",
|
||||
"dist",
|
||||
);
|
||||
}
|
||||
await confinedPath(
|
||||
"runtimeConfigSchema",
|
||||
manifest.outputs.runtimeConfigSchema,
|
||||
"file",
|
||||
"dist",
|
||||
);
|
||||
for (const [chunkId, chunkPath] of Object.entries(manifest.outputs.routeChunks)) {
|
||||
if (!isSafeRelativePath(chunkPath)) {
|
||||
mismatches.push(`buildManifest:routeChunk:${chunkId}:path`);
|
||||
continue;
|
||||
}
|
||||
await confinedPath(
|
||||
`routeChunk:${chunkId}`,
|
||||
path.posix.join(manifest.outputs.directory, chunkPath),
|
||||
"file",
|
||||
"dist",
|
||||
);
|
||||
}
|
||||
const moduleInventoryPath = await confinedPath(
|
||||
"moduleInventory",
|
||||
manifest.outputs.moduleInventory,
|
||||
"file",
|
||||
"artifacts/quality",
|
||||
);
|
||||
if (moduleInventoryPath) {
|
||||
try {
|
||||
const bytes = await readBytes(moduleInventoryPath);
|
||||
const digest = createHash("sha256").update(bytes).digest("hex");
|
||||
if (digest !== manifest.moduleInventoryHash) {
|
||||
mismatches.push("buildManifest:moduleInventoryHash");
|
||||
}
|
||||
try {
|
||||
moduleInventoryArtifactSchema.parse(JSON.parse(bytes.toString("utf8")));
|
||||
} catch {
|
||||
mismatches.push("buildManifest:moduleInventory:invalid");
|
||||
}
|
||||
} catch {
|
||||
mismatches.push("buildManifest:moduleInventory:missing");
|
||||
}
|
||||
}
|
||||
return mismatches;
|
||||
}
|
||||
@@ -0,0 +1,742 @@
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import { lstat, open, realpath } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { z, type ZodType } from "zod";
|
||||
|
||||
import type {
|
||||
CiGateArtifact,
|
||||
CiGateArtifactSchema,
|
||||
} from "../contracts/ci-gates.ts";
|
||||
import { ciContractReportSchema } from "./ci-contract-report.ts";
|
||||
import {
|
||||
architectureDependencyReportArtifactSchema,
|
||||
automatedA11yArtifactSchema,
|
||||
buildManifestArtifactSchema,
|
||||
bundlePerformanceArtifactSchema,
|
||||
compatibilityFixturesArtifactSchema,
|
||||
dependencyDiffArtifactSchema,
|
||||
dependencyInventoryArtifactSchema,
|
||||
designSystemReportArtifactSchema,
|
||||
diagnosticsReportArtifactSchema,
|
||||
documentationReviewArtifactSchema,
|
||||
fieldWebVitalsArtifactSchema,
|
||||
hostingHeadersArtifactSchema,
|
||||
i18nReportArtifactSchema,
|
||||
jsonSchemaDocumentArtifactSchema,
|
||||
labPerformanceArtifactSchema,
|
||||
licenseReportArtifactSchema,
|
||||
manualA11yReportArtifactSchema,
|
||||
moduleInventoryArtifactSchema,
|
||||
optionalRecipeFixturesArtifactSchema,
|
||||
optionalRecipesArtifactSchema,
|
||||
provenanceArtifactSchema,
|
||||
realtimeBoundariesArtifactSchema,
|
||||
registryGovernanceRunArtifactSchema,
|
||||
registryCompatibilityFixturesArtifactSchema,
|
||||
registrySnapshotArtifactSchema,
|
||||
deploymentAdmissionArtifactSchema,
|
||||
releaseVerificationArtifactSchema,
|
||||
reproducibleBuildArtifactSchema,
|
||||
runbookRecordArtifactSchema,
|
||||
sbomArtifactSchema,
|
||||
supplyChainFixturesArtifactSchema,
|
||||
supplyChainProviderFixturesArtifactSchema,
|
||||
supplyChainVerificationArtifactSchema,
|
||||
vulnerabilityReportArtifactSchema,
|
||||
} from "../contracts/release-artifacts.ts";
|
||||
import { httpScenarioReceiptSchema } from "./http-scenario-evidence.ts";
|
||||
import { supplyChainCoherenceReportSchema } from "./local-release-evidence.ts";
|
||||
import {
|
||||
providerVerificationArtifactSchema,
|
||||
provenanceProviderAttestationSchema,
|
||||
vulnerabilityProviderReportSchema,
|
||||
} from "./provider-evidence.ts";
|
||||
import { releaseCandidateManifestSchema } from "./release-candidate.ts";
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
import { secretScanSarifSchema } from "./secret-scan-evaluator.ts";
|
||||
import { testEvidenceReportSchema } from "./test-evidence-artifact.ts";
|
||||
|
||||
const coverageCounterSchema = z
|
||||
.object({
|
||||
total: z.number().int().nonnegative(),
|
||||
covered: z.number().int().nonnegative(),
|
||||
skipped: z.number().int().nonnegative(),
|
||||
pct: z.number().min(0).max(100),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((counter, context) => {
|
||||
if (counter.covered + counter.skipped > counter.total) {
|
||||
context.addIssue({ code: "custom", message: "coverage counter exceeds total" });
|
||||
}
|
||||
const expected = counter.total === 0
|
||||
? 100
|
||||
: Math.floor((counter.covered / counter.total) * 10_000) / 100;
|
||||
if (counter.pct !== expected) {
|
||||
context.addIssue({ code: "custom", path: ["pct"], message: "coverage pct is not exact" });
|
||||
}
|
||||
});
|
||||
const coverageSummarySchema = z
|
||||
.record(
|
||||
z.string(),
|
||||
z
|
||||
.object({
|
||||
lines: coverageCounterSchema,
|
||||
statements: coverageCounterSchema,
|
||||
functions: coverageCounterSchema,
|
||||
branches: coverageCounterSchema,
|
||||
})
|
||||
.strict(),
|
||||
)
|
||||
.refine((value) => "total" in value, "coverage summary lacks total");
|
||||
const riskCoverageArtifactSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(3),
|
||||
policy: z.string().min(1),
|
||||
summary: z.string().min(1),
|
||||
status: z.enum(["PASS", "FAIL"]),
|
||||
selectedTotal: z.number().int().nonnegative(),
|
||||
repositoryTotal: z.number().int().positive(),
|
||||
counterBearingTotal: z.number().int().nonnegative(),
|
||||
instrumentedCounterBearingTotal: z.number().int().nonnegative(),
|
||||
counterlessTotal: z.number().int().nonnegative(),
|
||||
counterlessModules: z.array(z.string()),
|
||||
preExclusionTotal: z.number().int().positive(),
|
||||
generatedExclusionCount: z.number().int().nonnegative(),
|
||||
generatedExclusions: z.array(z.string()),
|
||||
ownershipScope: z.literal("ALL_POLICY_HIGH_RISK"),
|
||||
ownedHighRiskPaths: z.array(z.string()),
|
||||
waivedHighRiskPaths: z.array(z.string()),
|
||||
uncoveredModules: z.array(z.string()),
|
||||
results: z
|
||||
.array(
|
||||
z
|
||||
.object({
|
||||
scope: z.string().min(1),
|
||||
metric: z.enum(["lines", "statements", "functions", "branches"]),
|
||||
threshold: z.number().min(0).max(100),
|
||||
received: z.number().min(0).max(100),
|
||||
passed: z.boolean(),
|
||||
})
|
||||
.strict(),
|
||||
)
|
||||
.min(4),
|
||||
failures: z.array(z.string()),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((artifact, context) => {
|
||||
const fail = (path: PropertyKey[], message: string) =>
|
||||
context.addIssue({ code: "custom", path, message });
|
||||
if (artifact.counterBearingTotal + artifact.counterlessTotal !== artifact.repositoryTotal) {
|
||||
fail(["counterBearingTotal"], "counter partition must equal repositoryTotal");
|
||||
}
|
||||
if (artifact.instrumentedCounterBearingTotal > artifact.counterBearingTotal) {
|
||||
fail(["instrumentedCounterBearingTotal"], "instrumented counters exceed counter-bearing total");
|
||||
}
|
||||
if (artifact.counterlessModules.length !== artifact.counterlessTotal) {
|
||||
fail(["counterlessModules"], "counterless list length drift");
|
||||
}
|
||||
if (artifact.generatedExclusions.length !== artifact.generatedExclusionCount) {
|
||||
fail(["generatedExclusions"], "generated exclusion list length drift");
|
||||
}
|
||||
if (
|
||||
artifact.preExclusionTotal !==
|
||||
artifact.repositoryTotal + artifact.generatedExclusionCount
|
||||
) {
|
||||
fail(["preExclusionTotal"], "pre-exclusion inventory total drift");
|
||||
}
|
||||
if (
|
||||
artifact.selectedTotal > artifact.repositoryTotal ||
|
||||
artifact.uncoveredModules.length !== artifact.repositoryTotal - artifact.selectedTotal
|
||||
) {
|
||||
fail(["selectedTotal"], "selected/uncovered repository totals drift");
|
||||
}
|
||||
if (
|
||||
(artifact.status === "PASS") !==
|
||||
(artifact.failures.length === 0 && artifact.results.every(({ passed }) => passed))
|
||||
) {
|
||||
fail(["status"], "status must agree with failures and threshold results");
|
||||
}
|
||||
artifact.results.forEach((result, index) => {
|
||||
if (result.passed !== (result.received >= result.threshold)) {
|
||||
fail(["results", index, "passed"], "threshold result is inconsistent");
|
||||
}
|
||||
});
|
||||
for (const [field, values] of [
|
||||
["counterlessModules", artifact.counterlessModules],
|
||||
["generatedExclusions", artifact.generatedExclusions],
|
||||
["ownedHighRiskPaths", artifact.ownedHighRiskPaths],
|
||||
["waivedHighRiskPaths", artifact.waivedHighRiskPaths],
|
||||
["uncoveredModules", artifact.uncoveredModules],
|
||||
] as const) {
|
||||
if (new Set(values).size !== values.length) fail([field], "path list contains duplicates");
|
||||
}
|
||||
const owned = new Set(artifact.ownedHighRiskPaths);
|
||||
if (artifact.waivedHighRiskPaths.some((modulePath) => owned.has(modulePath))) {
|
||||
fail(["waivedHighRiskPaths"], "owned and waived high-risk paths overlap");
|
||||
}
|
||||
const resultsByScope = new Map<string, Set<string>>();
|
||||
artifact.results.forEach(({ scope, metric }, index) => {
|
||||
const metrics = resultsByScope.get(scope) ?? new Set<string>();
|
||||
if (metrics.has(metric)) {
|
||||
fail(["results", index, "metric"], "threshold metric is duplicated within scope");
|
||||
}
|
||||
metrics.add(metric);
|
||||
resultsByScope.set(scope, metrics);
|
||||
});
|
||||
for (const [scope, metrics] of resultsByScope) {
|
||||
if (metrics.size !== 4) {
|
||||
fail(["results"], `threshold scope must contain all four metrics: ${scope}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
type ExecutableJsonSchemaId = Extract<
|
||||
CiGateArtifactSchema,
|
||||
Readonly<{ kind: "json" }>
|
||||
>["executableSchemaId"];
|
||||
|
||||
const executableJsonSchemas: Readonly<Record<ExecutableJsonSchemaId, ZodType>> = Object.freeze({
|
||||
"automated-a11y": automatedA11yArtifactSchema,
|
||||
"manual-a11y": manualA11yReportArtifactSchema,
|
||||
"architecture-dependency-report": architectureDependencyReportArtifactSchema,
|
||||
"design-system-contract": designSystemReportArtifactSchema,
|
||||
"i18n-contract": i18nReportArtifactSchema,
|
||||
"diagnostics-contract": diagnosticsReportArtifactSchema,
|
||||
"realtime-boundaries": realtimeBoundariesArtifactSchema,
|
||||
"optional-recipes": optionalRecipesArtifactSchema,
|
||||
"optional-recipe-fixtures": optionalRecipeFixturesArtifactSchema,
|
||||
"registry-compatibility-fixtures": registryCompatibilityFixturesArtifactSchema,
|
||||
"reproducible-build": reproducibleBuildArtifactSchema,
|
||||
"supply-chain-fixtures": supplyChainFixturesArtifactSchema,
|
||||
"supply-chain-provider-fixtures": supplyChainProviderFixturesArtifactSchema,
|
||||
"compatibility-fixtures": compatibilityFixturesArtifactSchema,
|
||||
"documentation-review": documentationReviewArtifactSchema,
|
||||
"hosting-headers": hostingHeadersArtifactSchema,
|
||||
"coverage-summary-v8": coverageSummarySchema,
|
||||
"risk-coverage-v3": riskCoverageArtifactSchema,
|
||||
"build-manifest": buildManifestArtifactSchema,
|
||||
"module-inventory": moduleInventoryArtifactSchema,
|
||||
"dependency-inventory": dependencyInventoryArtifactSchema,
|
||||
"registry-snapshot": registrySnapshotArtifactSchema,
|
||||
"registry-governance-run": registryGovernanceRunArtifactSchema,
|
||||
"bundle-performance": bundlePerformanceArtifactSchema,
|
||||
sbom: sbomArtifactSchema,
|
||||
provenance: provenanceArtifactSchema,
|
||||
"dependency-diff": dependencyDiffArtifactSchema,
|
||||
"license-report": licenseReportArtifactSchema,
|
||||
"vulnerability-report": vulnerabilityReportArtifactSchema,
|
||||
"field-web-vitals": fieldWebVitalsArtifactSchema,
|
||||
"lab-performance": labPerformanceArtifactSchema,
|
||||
"release-verification": releaseVerificationArtifactSchema,
|
||||
"runbook-record": runbookRecordArtifactSchema,
|
||||
"supply-chain-verification": supplyChainVerificationArtifactSchema,
|
||||
"release-candidate": releaseCandidateManifestSchema,
|
||||
"supply-chain-coherence": supplyChainCoherenceReportSchema,
|
||||
"http-scenario-receipt": httpScenarioReceiptSchema,
|
||||
"test-evidence-report": testEvidenceReportSchema,
|
||||
"provider-vulnerability": vulnerabilityProviderReportSchema,
|
||||
"provider-provenance": provenanceProviderAttestationSchema,
|
||||
"provider-verification": providerVerificationArtifactSchema,
|
||||
"ci-contract-report": ciContractReportSchema,
|
||||
"deployment-admission": deploymentAdmissionArtifactSchema,
|
||||
});
|
||||
|
||||
export function hasCiArtifactSemanticValidator(
|
||||
schema: CiGateArtifactSchema,
|
||||
): boolean {
|
||||
return schema.kind !== "json" || schema.executableSchemaId in executableJsonSchemas;
|
||||
}
|
||||
|
||||
type ReadHandle = Readonly<{
|
||||
stat(): Promise<Stats>;
|
||||
read(
|
||||
buffer: Buffer,
|
||||
offset: number,
|
||||
length: number,
|
||||
position: number,
|
||||
): Promise<Readonly<{ bytesRead: number }>>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
type ValidatorDependencies = Readonly<{
|
||||
lstatPath?: typeof lstat;
|
||||
realpathPath?: typeof realpath;
|
||||
openFile?: (target: string, flags: number) => Promise<ReadHandle>;
|
||||
}>;
|
||||
|
||||
export async function validateCiArtifact(
|
||||
input: Readonly<{
|
||||
root: string;
|
||||
artifact: CiGateArtifact;
|
||||
schema: CiGateArtifactSchema;
|
||||
}>,
|
||||
dependencies: ValidatorDependencies = {},
|
||||
): Promise<void> {
|
||||
const relative = normalizeRepositoryRelativePath(input.artifact.path, "CI artifact path");
|
||||
assertExtensionCoherence(relative, input.schema.kind);
|
||||
const bytes = await readBoundedRegularFile(
|
||||
{ root: input.root, relativePath: relative, maxBytes: input.schema.maxBytes },
|
||||
dependencies,
|
||||
);
|
||||
if (input.schema.kind === "candidate-archive") return;
|
||||
const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
|
||||
if (!text.trim()) throw new TypeError(`CI artifact is empty: ${relative}`);
|
||||
switch (input.schema.kind) {
|
||||
case "text":
|
||||
return;
|
||||
case "markdown":
|
||||
if (!/^#|\[[^\]]+\]|\S/u.test(text)) throw new TypeError(`invalid Markdown artifact: ${relative}`);
|
||||
return;
|
||||
case "html":
|
||||
assertWellFormedHtml(text, relative);
|
||||
return;
|
||||
case "junit":
|
||||
assertWellFormedJUnitXml(text, relative);
|
||||
return;
|
||||
case "sarif":
|
||||
secretScanSarifSchema.parse(JSON.parse(text) as unknown);
|
||||
return;
|
||||
case "json-schema":
|
||||
jsonSchemaDocumentArtifactSchema.parse(JSON.parse(text) as unknown);
|
||||
return;
|
||||
case "json": {
|
||||
const schema = executableJsonSchemas[input.schema.executableSchemaId];
|
||||
if (!schema) throw new TypeError(`unknown executable artifact schema: ${input.schema.executableSchemaId}`);
|
||||
schema.parse(JSON.parse(text) as unknown);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export async function readBoundedRegularFile(
|
||||
input: Readonly<{ root: string; relativePath: string; maxBytes: number }>,
|
||||
dependencies: ValidatorDependencies = {},
|
||||
): Promise<Buffer> {
|
||||
const root = path.resolve(input.root);
|
||||
const relative = normalizeRepositoryRelativePath(input.relativePath, "bounded file path");
|
||||
const maxBytes = input.maxBytes;
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 268_435_456) {
|
||||
throw new RangeError("bounded file maximum must be within 1..268435456");
|
||||
}
|
||||
const lstatPath = dependencies.lstatPath ?? lstat;
|
||||
const realpathPath = dependencies.realpathPath ?? realpath;
|
||||
const openFile = dependencies.openFile ?? (async (target, flags) => open(target, flags));
|
||||
const rootMetadata = await lstatPath(root);
|
||||
if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
|
||||
throw new TypeError("bounded file root is unsafe");
|
||||
}
|
||||
const rootRealpath = await realpathPath(root);
|
||||
let ancestor = root;
|
||||
const segments = relative.split("/");
|
||||
for (const segment of segments.slice(0, -1)) {
|
||||
ancestor = path.join(ancestor, segment);
|
||||
const metadata = await lstatPath(ancestor);
|
||||
if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
|
||||
throw new TypeError(`CI artifact ancestor is unsafe: ${relative}`);
|
||||
}
|
||||
}
|
||||
const absolute = path.join(root, relative);
|
||||
const before = await lstatPath(absolute);
|
||||
if (before.isSymbolicLink() || !before.isFile()) {
|
||||
throw new TypeError(`CI artifact is not a regular file: ${relative}`);
|
||||
}
|
||||
if (before.size <= 0 || before.size > maxBytes) {
|
||||
throw new RangeError(`CI artifact size is outside 1..${maxBytes}: ${relative}`);
|
||||
}
|
||||
const resolved = await realpathPath(absolute);
|
||||
const outside = path.relative(rootRealpath, resolved);
|
||||
if (outside === ".." || outside.startsWith(`..${path.sep}`) || path.isAbsolute(outside)) {
|
||||
throw new TypeError(`CI artifact escapes repository: ${relative}`);
|
||||
}
|
||||
const handle = await openFile(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
|
||||
try {
|
||||
const opened = await handle.stat();
|
||||
assertSameIdentity(before, opened, relative);
|
||||
const bytes = await readHandleBounded(handle, before.size, maxBytes, relative);
|
||||
const after = await handle.stat();
|
||||
assertSameIdentity(opened, after, relative);
|
||||
if (bytes.byteLength <= 0 || bytes.byteLength > maxBytes || after.size !== bytes.byteLength) {
|
||||
throw new RangeError(`CI artifact changed size or exceeds bound: ${relative}`);
|
||||
}
|
||||
return bytes;
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
}
|
||||
|
||||
async function readHandleBounded(
|
||||
handle: ReadHandle,
|
||||
expectedSize: number,
|
||||
maxBytes: number,
|
||||
relative: string,
|
||||
): Promise<Buffer> {
|
||||
const captured = Buffer.allocUnsafe(Math.min(maxBytes + 1, expectedSize + 1));
|
||||
let offset = 0;
|
||||
while (offset < captured.byteLength) {
|
||||
const { bytesRead } = await handle.read(
|
||||
captured,
|
||||
offset,
|
||||
captured.byteLength - offset,
|
||||
offset,
|
||||
);
|
||||
if (bytesRead === 0) break;
|
||||
offset += bytesRead;
|
||||
}
|
||||
if (offset !== expectedSize) {
|
||||
throw new RangeError(`CI artifact changed size or exceeds bound: ${relative}`);
|
||||
}
|
||||
return captured.subarray(0, offset);
|
||||
}
|
||||
|
||||
const MAX_DOCUMENT_DEPTH = 256;
|
||||
const MAX_DOCUMENT_UNITS = 100_000;
|
||||
|
||||
function assertWellFormedJUnitXml(source: string, relative: string): void {
|
||||
const invalid = () => new TypeError(`invalid JUnit artifact: ${relative}`);
|
||||
if (/<!DOCTYPE\b|<!ENTITY\b/iu.test(source)) throw invalid();
|
||||
if (!hasOnlyXmlCharacters(source)) throw invalid();
|
||||
const stack: string[] = [];
|
||||
let root: string | undefined;
|
||||
let rootClosed = false;
|
||||
let declarationSeen = false;
|
||||
let units = 0;
|
||||
let cursor = 0;
|
||||
while (cursor < source.length) {
|
||||
const open = source.indexOf("<", cursor);
|
||||
const text = source.slice(cursor, open < 0 ? source.length : open);
|
||||
if (stack.length === 0 && text.trim()) throw invalid();
|
||||
if ((text.includes("]]>") || !hasValidXmlEntities(text)) && text.length > 0) throw invalid();
|
||||
if (text.length > 0 && ++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
if (open < 0) break;
|
||||
if (source.startsWith("<!--", open)) {
|
||||
const close = source.indexOf("-->", open + 4);
|
||||
if (close < 0 || source.slice(open + 4, close).includes("--")) throw invalid();
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 3;
|
||||
continue;
|
||||
}
|
||||
if (source.startsWith("<![CDATA[", open)) {
|
||||
const close = source.indexOf("]]>", open + 9);
|
||||
if (stack.length === 0 || close < 0) throw invalid();
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 3;
|
||||
continue;
|
||||
}
|
||||
if (source.startsWith("<?", open)) {
|
||||
const close = source.indexOf("?>", open + 2);
|
||||
if (root || close < 0) throw invalid();
|
||||
const processingInstruction = source.slice(open, close + 2);
|
||||
const match = /^<\?([A-Za-z_][\w:.-]*)(?:\s+[\s\S]*?)?\?>$/u.exec(
|
||||
processingInstruction,
|
||||
);
|
||||
if (!match) throw invalid();
|
||||
if (match[1]!.toLowerCase() === "xml") {
|
||||
if (
|
||||
declarationSeen ||
|
||||
source.slice(0, open).trim() ||
|
||||
!/^<\?xml\s+version\s*=\s*(["'])1\.0\1(?:\s+encoding\s*=\s*(["'])UTF-8\2)?\s*\?>$/u.test(
|
||||
processingInstruction,
|
||||
)
|
||||
) {
|
||||
throw invalid();
|
||||
}
|
||||
declarationSeen = true;
|
||||
}
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 2;
|
||||
continue;
|
||||
}
|
||||
if (source.startsWith("<!", open)) throw invalid();
|
||||
const close = markupEnd(source, open + 1);
|
||||
if (close < 0) throw invalid();
|
||||
const tag = source.slice(open, close + 1);
|
||||
const closing = /^<\/([A-Za-z_][\w:.-]*)\s*>$/u.exec(tag);
|
||||
if (closing) {
|
||||
if (stack.pop() !== closing[1]) throw invalid();
|
||||
if (stack.length === 0) rootClosed = true;
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 1;
|
||||
continue;
|
||||
}
|
||||
const opening = /^<([A-Za-z_][\w:.-]*)([\s\S]*?)(\/?)>$/u.exec(tag);
|
||||
if (!opening || rootClosed || !hasValidXmlAttributes(opening[2] ?? "")) throw invalid();
|
||||
root ??= opening[1];
|
||||
if (opening[3] !== "/") {
|
||||
if (stack.length >= MAX_DOCUMENT_DEPTH) throw invalid();
|
||||
stack.push(opening[1]!);
|
||||
}
|
||||
else if (stack.length === 0) rootClosed = true;
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 1;
|
||||
}
|
||||
if (stack.length > 0 || !rootClosed || (root !== "testsuite" && root !== "testsuites")) {
|
||||
throw invalid();
|
||||
}
|
||||
}
|
||||
|
||||
function hasValidXmlAttributes(source: string): boolean {
|
||||
let remaining = source;
|
||||
const names = new Set<string>();
|
||||
while (remaining.length > 0) {
|
||||
if (!remaining.trim()) return true;
|
||||
const match = /^\s+([A-Za-z_:][\w:.-]*)\s*=\s*(?:"([^"<]*)"|'([^'<]*)')/u.exec(remaining);
|
||||
if (!match || names.has(match[1]!)) return false;
|
||||
if (!hasValidXmlEntities(match[2] ?? match[3] ?? "")) return false;
|
||||
names.add(match[1]!);
|
||||
remaining = remaining.slice(match[0].length);
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function hasOnlyXmlCharacters(source: string): boolean {
|
||||
for (const character of source) {
|
||||
const codePoint = character.codePointAt(0)!;
|
||||
if (
|
||||
codePoint !== 0x09 &&
|
||||
codePoint !== 0x0a &&
|
||||
codePoint !== 0x0d &&
|
||||
(codePoint < 0x20 ||
|
||||
(codePoint > 0xd7ff && codePoint < 0xe000) ||
|
||||
(codePoint > 0xfffd && codePoint < 0x10000) ||
|
||||
codePoint > 0x10ffff)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function hasValidXmlEntities(source: string): boolean {
|
||||
let cursor = 0;
|
||||
while (cursor < source.length) {
|
||||
const ampersand = source.indexOf("&", cursor);
|
||||
if (ampersand < 0) return true;
|
||||
const semicolon = source.indexOf(";", ampersand + 1);
|
||||
if (semicolon < 0) return false;
|
||||
const entity = source.slice(ampersand + 1, semicolon);
|
||||
if (!["amp", "lt", "gt", "apos", "quot"].includes(entity)) {
|
||||
const decimal = /^#([0-9]+)$/u.exec(entity);
|
||||
const hexadecimal = /^#x([a-fA-F0-9]+)$/u.exec(entity);
|
||||
if (!decimal && !hexadecimal) return false;
|
||||
const codePoint = Number.parseInt((decimal ?? hexadecimal)![1]!, decimal ? 10 : 16);
|
||||
if (
|
||||
!Number.isSafeInteger(codePoint) ||
|
||||
(codePoint !== 0x09 &&
|
||||
codePoint !== 0x0a &&
|
||||
codePoint !== 0x0d &&
|
||||
(codePoint < 0x20 ||
|
||||
(codePoint > 0xd7ff && codePoint < 0xe000) ||
|
||||
(codePoint > 0xfffd && codePoint < 0x10000) ||
|
||||
codePoint > 0x10ffff))
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
cursor = semicolon + 1;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
const HTML_VOID_ELEMENTS = new Set([
|
||||
"area",
|
||||
"base",
|
||||
"br",
|
||||
"col",
|
||||
"embed",
|
||||
"hr",
|
||||
"img",
|
||||
"input",
|
||||
"link",
|
||||
"meta",
|
||||
"param",
|
||||
"source",
|
||||
"track",
|
||||
"wbr",
|
||||
]);
|
||||
const HTML_RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
|
||||
|
||||
function assertWellFormedHtml(source: string, relative: string): void {
|
||||
const invalid = () => new TypeError(`invalid HTML artifact: ${relative}`);
|
||||
if (/<!ENTITY\b|<!DOCTYPE\s+html\s+[^>]*\[/iu.test(source)) throw invalid();
|
||||
const stack: string[] = [];
|
||||
let cursor = 0;
|
||||
let units = 0;
|
||||
let doctypeSeen = false;
|
||||
let rootSeen = false;
|
||||
let rootClosed = false;
|
||||
let playwrightPayloadSeen = false;
|
||||
while (cursor < source.length) {
|
||||
const rawElement = stack.at(-1);
|
||||
if (rawElement && HTML_RAW_TEXT_ELEMENTS.has(rawElement)) {
|
||||
const closingStart = source.toLowerCase().indexOf(`</${rawElement}`, cursor);
|
||||
if (closingStart < 0) throw invalid();
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = closingStart;
|
||||
}
|
||||
const open = source.indexOf("<", cursor);
|
||||
const text = source.slice(cursor, open < 0 ? source.length : open);
|
||||
if (stack.length === 0 && text.trim()) throw invalid();
|
||||
if (text.length > 0 && ++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
if (open < 0) break;
|
||||
if (source.startsWith("<!--", open)) {
|
||||
const close = source.indexOf("-->", open + 4);
|
||||
if (close < 0 || source.slice(open + 4, close).includes("--")) throw invalid();
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 3;
|
||||
continue;
|
||||
}
|
||||
const declarationEnd = source.indexOf(">", open + 2);
|
||||
if (source.slice(open, open + 9).toLowerCase() === "<!doctype") {
|
||||
if (
|
||||
declarationEnd < 0 ||
|
||||
doctypeSeen ||
|
||||
rootSeen ||
|
||||
source.slice(open, declarationEnd + 1).toLowerCase() !== "<!doctype html>"
|
||||
) {
|
||||
throw invalid();
|
||||
}
|
||||
doctypeSeen = true;
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = declarationEnd + 1;
|
||||
continue;
|
||||
}
|
||||
if (source.startsWith("<!", open) || source.startsWith("<?", open)) throw invalid();
|
||||
const close = markupEnd(source, open + 1);
|
||||
if (close < 0) throw invalid();
|
||||
const tag = source.slice(open, close + 1);
|
||||
const closing = /^<\/([A-Za-z][A-Za-z0-9:-]*)\s*>$/u.exec(tag);
|
||||
if (closing) {
|
||||
const name = closing[1]!.toLowerCase();
|
||||
if (stack.pop() !== name) throw invalid();
|
||||
if (stack.length === 0) {
|
||||
if (name === "html") rootClosed = true;
|
||||
else if (name === "template" && playwrightPayloadSeen) {
|
||||
// Playwright emits its base64 report template after </html>; HTML5
|
||||
// reparents this token into the document body. It is the sole
|
||||
// permitted generated-report sidecar and does not create a new root.
|
||||
} else {
|
||||
throw invalid();
|
||||
}
|
||||
}
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 1;
|
||||
continue;
|
||||
}
|
||||
const opening = /^<([A-Za-z][A-Za-z0-9:-]*)([\s\S]*?)(\/?)>$/u.exec(tag);
|
||||
if (!opening) throw invalid();
|
||||
const name = opening[1]!.toLowerCase();
|
||||
const attributes = parseHtmlAttributes(opening[2] ?? "");
|
||||
if (!attributes || name.includes(":")) throw invalid();
|
||||
if (!rootSeen) {
|
||||
if (name !== "html" || opening[3] === "/") throw invalid();
|
||||
rootSeen = true;
|
||||
} else if (name === "html") {
|
||||
throw invalid();
|
||||
}
|
||||
if (rootClosed && stack.length === 0) {
|
||||
if (
|
||||
playwrightPayloadSeen ||
|
||||
name !== "template" ||
|
||||
attributes.get("id") !== "playwrightReportBase64" ||
|
||||
opening[3] === "/"
|
||||
) {
|
||||
throw invalid();
|
||||
}
|
||||
playwrightPayloadSeen = true;
|
||||
}
|
||||
if (!HTML_VOID_ELEMENTS.has(name) && opening[3] !== "/") {
|
||||
if (stack.length >= MAX_DOCUMENT_DEPTH) throw invalid();
|
||||
stack.push(name);
|
||||
} else if (stack.length === 0 && name === "html") {
|
||||
rootClosed = true;
|
||||
}
|
||||
if (++units > MAX_DOCUMENT_UNITS) throw invalid();
|
||||
cursor = close + 1;
|
||||
}
|
||||
if (stack.length > 0 || !rootSeen || !rootClosed) throw invalid();
|
||||
}
|
||||
|
||||
function markupEnd(source: string, start: number): number {
|
||||
let quote: "\"" | "'" | undefined;
|
||||
for (let index = start; index < source.length; index += 1) {
|
||||
const character = source[index];
|
||||
if (quote) {
|
||||
if (character === quote) quote = undefined;
|
||||
} else if (character === "\"" || character === "'") {
|
||||
quote = character;
|
||||
} else if (character === ">") {
|
||||
return index;
|
||||
}
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
function parseHtmlAttributes(source: string): ReadonlyMap<string, string> | null {
|
||||
const attributes = new Map<string, string>();
|
||||
let cursor = 0;
|
||||
while (cursor < source.length) {
|
||||
const whitespace = /^\s+/u.exec(source.slice(cursor));
|
||||
if (!whitespace) return source.slice(cursor).trim() ? null : attributes;
|
||||
cursor += whitespace[0].length;
|
||||
if (cursor >= source.length) return attributes;
|
||||
const nameMatch = /^[A-Za-z_:][A-Za-z0-9:._-]*/u.exec(source.slice(cursor));
|
||||
if (!nameMatch) return null;
|
||||
const name = nameMatch[0].toLowerCase();
|
||||
if (attributes.has(name) || name.includes(":")) return null;
|
||||
cursor += nameMatch[0].length;
|
||||
const spacing = /^\s*/u.exec(source.slice(cursor))![0];
|
||||
cursor += spacing.length;
|
||||
let value = "";
|
||||
if (source[cursor] === "=") {
|
||||
cursor += 1;
|
||||
cursor += /^\s*/u.exec(source.slice(cursor))![0].length;
|
||||
const quote = source[cursor];
|
||||
if (quote === "\"" || quote === "'") {
|
||||
const end = source.indexOf(quote, cursor + 1);
|
||||
if (end < 0) return null;
|
||||
value = source.slice(cursor + 1, end);
|
||||
if (value.includes("<")) return null;
|
||||
cursor = end + 1;
|
||||
} else {
|
||||
const unquoted = /^[^\s"'`=<>]+/u.exec(source.slice(cursor));
|
||||
if (!unquoted) return null;
|
||||
value = unquoted[0];
|
||||
cursor += value.length;
|
||||
}
|
||||
}
|
||||
attributes.set(name, value);
|
||||
}
|
||||
return attributes;
|
||||
}
|
||||
|
||||
function assertSameIdentity(before: Stats, after: Stats, relative: string): void {
|
||||
if (
|
||||
!Number.isSafeInteger(before.dev) ||
|
||||
!Number.isSafeInteger(before.ino) ||
|
||||
before.dev <= 0 ||
|
||||
before.ino <= 0 ||
|
||||
before.dev !== after.dev ||
|
||||
before.ino !== after.ino ||
|
||||
!after.isFile()
|
||||
) {
|
||||
throw new TypeError(`CI artifact file identity changed: ${relative}`);
|
||||
}
|
||||
}
|
||||
|
||||
function assertExtensionCoherence(relative: string, kind: CiGateArtifactSchema["kind"]): void {
|
||||
const valid =
|
||||
kind === "json" || kind === "json-schema"
|
||||
? relative.endsWith(".json")
|
||||
: kind === "sarif"
|
||||
? relative.endsWith(".sarif")
|
||||
: kind === "junit"
|
||||
? relative.endsWith(".xml")
|
||||
: kind === "html"
|
||||
? relative.endsWith(".html")
|
||||
: kind === "markdown"
|
||||
? relative.endsWith(".md")
|
||||
: kind === "candidate-archive"
|
||||
? relative.endsWith(".tar.gz")
|
||||
: !/\.(?:json|sarif|xml|html|md|tar\.gz)$/u.test(relative);
|
||||
if (!valid) throw new TypeError(`CI artifact extension/kind mismatch: ${relative} (${kind})`);
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
export const CANDIDATE_ARCHIVE_USAGE =
|
||||
"Usage: verify-ci-candidate-archive --archive <path> [--extract-to <path>] [--github-output <path>]\n";
|
||||
|
||||
export function parseCandidateArchiveArguments(arguments_: readonly string[]): Readonly<{
|
||||
archivePath: string;
|
||||
extractTo?: string;
|
||||
githubOutput?: string;
|
||||
}> | null {
|
||||
const allowed = new Set(["--archive", "--extract-to", "--github-output"]);
|
||||
const values = new Map<string, string>();
|
||||
for (let index = 0; index < arguments_.length; index += 2) {
|
||||
const flag = arguments_[index];
|
||||
const value = arguments_[index + 1];
|
||||
if (!flag || !allowed.has(flag) || values.has(flag) || !value || value.startsWith("--")) {
|
||||
return null;
|
||||
}
|
||||
values.set(flag, value);
|
||||
}
|
||||
const archivePath = values.get("--archive");
|
||||
if (!archivePath) return null;
|
||||
return Object.freeze({
|
||||
archivePath,
|
||||
...(values.has("--extract-to") ? { extractTo: values.get("--extract-to")! } : {}),
|
||||
...(values.has("--github-output") ? { githubOutput: values.get("--github-output")! } : {}),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,679 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import { constants } from "node:fs";
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
import {
|
||||
lstat,
|
||||
mkdir,
|
||||
open,
|
||||
readFile,
|
||||
readdir,
|
||||
rename,
|
||||
rm,
|
||||
unlink,
|
||||
} from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
RELEASE_CANDIDATE_EVIDENCE_PATHS,
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
distSha256,
|
||||
releaseCandidateManifestSchema,
|
||||
type ReleaseCandidateManifest,
|
||||
} from "./release-candidate.ts";
|
||||
import { supplyChainDigest } from "./supply-chain.ts";
|
||||
import {
|
||||
assertSafePublishLeaf,
|
||||
ensureSafePublishDirectory,
|
||||
} from "./ci-gate-log.ts";
|
||||
import {
|
||||
makePrivateTemporaryDirectory,
|
||||
withPrivateUmask,
|
||||
} from "./private-filesystem.ts";
|
||||
|
||||
const MAX_ARCHIVE_BYTES = 268_435_456;
|
||||
const MAX_CANDIDATE_FILES = 4_096;
|
||||
const MAX_ARCHIVE_MEMBERS = 8_192;
|
||||
const MAX_MEMBER_PATH_BYTES = 1_024;
|
||||
const TAR_EXECUTABLE = "/usr/bin/tar";
|
||||
const TAR_ENVIRONMENT = Object.freeze({ PATH: "/usr/bin:/bin", LC_ALL: "C", LANG: "C" });
|
||||
|
||||
export type CapturedCandidateArchive = Readonly<{
|
||||
bytes: Buffer;
|
||||
archiveSha256: string;
|
||||
}>;
|
||||
|
||||
export async function captureCiCandidateArchive(input: Readonly<{
|
||||
archivePath: string;
|
||||
expectedSha256: string;
|
||||
}>): Promise<CapturedCandidateArchive> {
|
||||
if (!/^[a-f0-9]{64}$/u.test(input.expectedSha256)) {
|
||||
throw new TypeError("expected candidate archive SHA-256 is invalid");
|
||||
}
|
||||
const absolute = path.resolve(input.archivePath);
|
||||
const before = await lstat(absolute);
|
||||
if (!before.isFile() || before.isSymbolicLink()) {
|
||||
throw new TypeError("candidate archive must be a regular non-symlink file");
|
||||
}
|
||||
if (before.size <= 0 || before.size > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError(`candidate archive size is outside 1..${MAX_ARCHIVE_BYTES}`);
|
||||
}
|
||||
const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
|
||||
let bytes: Buffer;
|
||||
try {
|
||||
assertSameIdentity(before, await handle.stat());
|
||||
bytes = await readCapturedArchive(handle, before.size);
|
||||
assertSameIdentity(before, await handle.stat());
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
const archiveSha256 = createHash("sha256").update(bytes).digest("hex");
|
||||
if (archiveSha256 !== input.expectedSha256) {
|
||||
throw new Error("candidate archive SHA-256 mismatch");
|
||||
}
|
||||
return Object.freeze({ bytes, archiveSha256 });
|
||||
}
|
||||
|
||||
export async function withVerifiedCapturedCandidate<T>(input: Readonly<{
|
||||
captured: CapturedCandidateArchive;
|
||||
verify: (view: Readonly<{
|
||||
extractionRoot: string;
|
||||
manifest: ReleaseCandidateManifest;
|
||||
}>) => Promise<T>;
|
||||
}>): Promise<T> {
|
||||
let result: T | undefined;
|
||||
await verifyCapturedCiCandidateArchive(
|
||||
input.captured.bytes,
|
||||
input.captured.archiveSha256,
|
||||
{
|
||||
verifyExtracted: async (extractionRoot, manifest) => {
|
||||
result = await input.verify({ extractionRoot, manifest });
|
||||
},
|
||||
},
|
||||
);
|
||||
return result as T;
|
||||
}
|
||||
|
||||
export async function verifyCiCandidateArchive(
|
||||
input: Readonly<{
|
||||
archivePath: string;
|
||||
expectedSha256?: string;
|
||||
extractTo?: string;
|
||||
repositoryRoot?: string;
|
||||
}>,
|
||||
dependencies: Readonly<{ afterArchiveRead?: () => Promise<void> }> = {},
|
||||
): Promise<Readonly<{
|
||||
archiveSha256: string;
|
||||
memberCount: number;
|
||||
manifest: ReleaseCandidateManifest;
|
||||
}>> {
|
||||
if (input.expectedSha256 && !/^[a-f0-9]{64}$/u.test(input.expectedSha256)) {
|
||||
throw new TypeError("expected candidate archive SHA-256 is invalid");
|
||||
}
|
||||
const absolute = path.resolve(input.archivePath);
|
||||
const before = await lstat(absolute);
|
||||
if (!before.isFile() || before.isSymbolicLink()) {
|
||||
throw new TypeError("candidate archive must be a regular non-symlink file");
|
||||
}
|
||||
if (before.size <= 0 || before.size > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError(`candidate archive size is outside 1..${MAX_ARCHIVE_BYTES}`);
|
||||
}
|
||||
const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
|
||||
let archive: Buffer;
|
||||
try {
|
||||
assertSameIdentity(before, await handle.stat());
|
||||
archive = await readCapturedArchive(handle, before.size);
|
||||
assertSameIdentity(before, await handle.stat());
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
if (archive.byteLength !== before.size) {
|
||||
throw new Error("candidate archive changed size during capture");
|
||||
}
|
||||
await dependencies.afterArchiveRead?.();
|
||||
const archiveSha256 = createHash("sha256").update(archive).digest("hex");
|
||||
if (input.expectedSha256 && archiveSha256 !== input.expectedSha256) {
|
||||
throw new Error("candidate archive SHA-256 mismatch");
|
||||
}
|
||||
|
||||
const extractionTarget = input.extractTo ? path.resolve(input.extractTo) : undefined;
|
||||
let extractionRoot: string;
|
||||
let extractionParentIdentity: Awaited<ReturnType<typeof ensureSafePublishDirectory>> | undefined;
|
||||
if (extractionTarget) {
|
||||
if (!input.repositoryRoot) {
|
||||
throw new TypeError("repositoryRoot is required when publishing an extracted candidate");
|
||||
}
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot);
|
||||
extractionParentIdentity = await ensureSafePublishDirectory(
|
||||
repositoryRoot,
|
||||
path.dirname(extractionTarget),
|
||||
);
|
||||
await assertSafePublishLeaf(extractionTarget, input.extractTo);
|
||||
extractionRoot = makePrivateTemporaryDirectory(
|
||||
path.join(path.dirname(extractionTarget), `.${path.basename(extractionTarget)}.verified-`),
|
||||
);
|
||||
} else {
|
||||
extractionRoot = makePrivateTemporaryDirectory(path.join(tmpdir(), "ci-candidate-archive-"));
|
||||
}
|
||||
let published = false;
|
||||
try {
|
||||
const captured = await materializeCapturedArchive(archive);
|
||||
try {
|
||||
const preflightManifest = preflightArchiveHandle(captured.handle);
|
||||
extractArchiveHandle(captured.handle, extractionRoot);
|
||||
const verified = await verifyExtractedTree(extractionRoot, preflightManifest);
|
||||
if (extractionTarget) {
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot!);
|
||||
const currentParentIdentity = await ensureSafePublishDirectory(
|
||||
repositoryRoot,
|
||||
path.dirname(extractionTarget),
|
||||
);
|
||||
if (
|
||||
!extractionParentIdentity ||
|
||||
extractionParentIdentity.dev <= 0 ||
|
||||
extractionParentIdentity.ino <= 0 ||
|
||||
currentParentIdentity.dev !== extractionParentIdentity.dev ||
|
||||
currentParentIdentity.ino !== extractionParentIdentity.ino
|
||||
) {
|
||||
throw new Error("verified extraction parent identity changed");
|
||||
}
|
||||
await assertSafePublishLeaf(extractionTarget, input.extractTo);
|
||||
if (await pathExists(extractionTarget)) {
|
||||
throw new Error(`verified extraction target already exists: ${input.extractTo}`);
|
||||
}
|
||||
await rename(extractionRoot, extractionTarget);
|
||||
published = true;
|
||||
}
|
||||
return Object.freeze({
|
||||
archiveSha256,
|
||||
memberCount: verified.memberCount,
|
||||
manifest: verified.manifest,
|
||||
});
|
||||
} finally {
|
||||
await captured.handle.close();
|
||||
await rm(captured.root, { recursive: true, force: true });
|
||||
}
|
||||
} finally {
|
||||
if (!published) await rm(extractionRoot, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
export async function verifyCapturedCiCandidateArchive(
|
||||
archive: Buffer,
|
||||
expectedSha256: string,
|
||||
dependencies: Readonly<{
|
||||
verifyExtracted?: (
|
||||
extractionRoot: string,
|
||||
manifest: ReleaseCandidateManifest,
|
||||
) => Promise<void>;
|
||||
}> = {},
|
||||
): Promise<Readonly<{
|
||||
archiveSha256: string;
|
||||
memberCount: number;
|
||||
manifest: ReleaseCandidateManifest;
|
||||
}>> {
|
||||
if (archive.byteLength <= 0 || archive.byteLength > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError(`candidate archive size is outside 1..${MAX_ARCHIVE_BYTES}`);
|
||||
}
|
||||
if (!/^[a-f0-9]{64}$/u.test(expectedSha256)) {
|
||||
throw new TypeError("expected candidate archive SHA-256 is invalid");
|
||||
}
|
||||
const archiveSha256 = createHash("sha256").update(archive).digest("hex");
|
||||
if (archiveSha256 !== expectedSha256) {
|
||||
throw new Error("candidate archive SHA-256 mismatch");
|
||||
}
|
||||
const captured = await materializeCapturedArchive(archive);
|
||||
const extractionRoot = makePrivateTemporaryDirectory(path.join(tmpdir(), "ci-captured-candidate-"));
|
||||
try {
|
||||
const manifest = preflightArchiveHandle(captured.handle);
|
||||
extractArchiveHandle(captured.handle, extractionRoot);
|
||||
const verified = await verifyExtractedTree(extractionRoot, manifest);
|
||||
await dependencies.verifyExtracted?.(extractionRoot, verified.manifest);
|
||||
return Object.freeze({
|
||||
archiveSha256,
|
||||
memberCount: verified.memberCount,
|
||||
manifest: verified.manifest,
|
||||
});
|
||||
} finally {
|
||||
await rm(extractionRoot, { recursive: true, force: true });
|
||||
await captured.handle.close();
|
||||
await rm(captured.root, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
function preflightArchiveHandle(archiveHandle: FileHandle): ReleaseCandidateManifest {
|
||||
const listed = spawnSync(
|
||||
TAR_EXECUTABLE,
|
||||
["--list", "--verbose", "--numeric-owner", "--full-time", "--gzip", "--file", "/proc/self/fd/3"],
|
||||
{
|
||||
encoding: "utf8",
|
||||
maxBuffer: 16_777_216,
|
||||
timeout: 10_000,
|
||||
env: TAR_ENVIRONMENT,
|
||||
stdio: ["ignore", "pipe", "pipe", archiveHandle.fd],
|
||||
},
|
||||
);
|
||||
if (listed.status !== 0 || listed.signal || listed.error) {
|
||||
throw new Error(
|
||||
`candidate archive listing failed: ${listed.stderr || listed.error?.message || listed.signal}`,
|
||||
);
|
||||
}
|
||||
const seen = new Set<string>();
|
||||
const regularMembers = new Set<string>();
|
||||
const directoryMembers = new Set<string>();
|
||||
let totalBytes = 0;
|
||||
const lines = listed.stdout.split(/\r?\n/u).filter(Boolean);
|
||||
if (lines.length === 0 || lines.length > MAX_ARCHIVE_MEMBERS) {
|
||||
throw new RangeError(`candidate archive member count is outside 1..${MAX_ARCHIVE_MEMBERS}`);
|
||||
}
|
||||
for (const line of lines) {
|
||||
const match = /^(?<mode>.{10})\s+\d+\/\d+\s+(?<bytes>\d+)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:\s+[+-]\d{4})?\s+(?<path>.+)$/u.exec(line);
|
||||
if (!match?.groups) throw new Error(`candidate archive listing is unparseable: ${line}`);
|
||||
const member = match.groups.path!.endsWith("/")
|
||||
? match.groups.path!.slice(0, -1)
|
||||
: match.groups.path!;
|
||||
assertSafeMemberPath(member);
|
||||
if (seen.has(member)) throw new Error(`candidate archive duplicate member: ${member}`);
|
||||
seen.add(member);
|
||||
const mode = match.groups.mode!;
|
||||
if (!mode.startsWith("-") && !mode.startsWith("d")) {
|
||||
throw new Error(`candidate archive contains non-regular member: ${member}`);
|
||||
}
|
||||
if (mode.startsWith("-")) {
|
||||
const memberBytes = Number(match.groups.bytes);
|
||||
if (
|
||||
member === RELEASE_CANDIDATE_MANIFEST_PATH &&
|
||||
memberBytes > 8_388_608
|
||||
) {
|
||||
throw new RangeError("candidate manifest exceeds 8388608 bytes");
|
||||
}
|
||||
totalBytes += memberBytes;
|
||||
if (!Number.isSafeInteger(totalBytes) || totalBytes > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError("candidate archive expanded bytes exceed the bound");
|
||||
}
|
||||
regularMembers.add(member);
|
||||
} else {
|
||||
directoryMembers.add(member);
|
||||
}
|
||||
}
|
||||
const manifest = readManifestFromArchive(archiveHandle);
|
||||
validateManifestSemantics(manifest);
|
||||
const expectedFiles = new Set([
|
||||
...manifest.files.map(({ path: member }) => member),
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
]);
|
||||
for (const member of expectedFiles) assertSafeMemberPath(member);
|
||||
const expectedDirectories = new Set(
|
||||
directoryAncestors([...expectedFiles]).filter(
|
||||
(member) => member === "dist" || member.startsWith("dist/"),
|
||||
),
|
||||
);
|
||||
if (
|
||||
JSON.stringify([...regularMembers].sort(asciiCompare)) !==
|
||||
JSON.stringify([...expectedFiles].sort(asciiCompare)) ||
|
||||
JSON.stringify([...directoryMembers].sort(asciiCompare)) !==
|
||||
JSON.stringify([...expectedDirectories].sort(asciiCompare))
|
||||
) {
|
||||
throw new Error("candidate archive exact member set drift before extraction");
|
||||
}
|
||||
return manifest;
|
||||
}
|
||||
|
||||
function extractArchiveHandle(archiveHandle: FileHandle, extractionRoot: string): void {
|
||||
// `--no-same-permissions` is what keeps an untrusted archive from choosing
|
||||
// its own modes, but it hands the decision to the inherited umask instead.
|
||||
// Under a hardened `umask 077x` tar then creates directories it cannot
|
||||
// descend into and extraction fails part-way. Pinning the umask for the
|
||||
// duration makes the extracted tree exactly private, whatever the caller's
|
||||
// ambient state is. `spawnSync` keeps this window free of interleaved work.
|
||||
const extracted = withPrivateUmask(() =>
|
||||
spawnSync(
|
||||
TAR_EXECUTABLE,
|
||||
[
|
||||
"--extract",
|
||||
"--gzip",
|
||||
"--file",
|
||||
"/proc/self/fd/3",
|
||||
"--directory",
|
||||
extractionRoot,
|
||||
"--no-same-owner",
|
||||
"--no-same-permissions",
|
||||
],
|
||||
{
|
||||
encoding: "utf8",
|
||||
maxBuffer: 1_048_576,
|
||||
timeout: 30_000,
|
||||
env: TAR_ENVIRONMENT,
|
||||
stdio: ["ignore", "pipe", "pipe", archiveHandle.fd],
|
||||
},
|
||||
),
|
||||
);
|
||||
if (extracted.status !== 0 || extracted.signal || extracted.error) {
|
||||
throw new Error(
|
||||
`candidate archive isolated extraction failed: ${extracted.stderr || extracted.error?.message || extracted.signal}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function validateManifestSemantics(manifest: ReleaseCandidateManifest): void {
|
||||
if (manifest.files.length === 0 || manifest.files.length > MAX_CANDIDATE_FILES) {
|
||||
throw new RangeError(`candidate manifest exceeds ${MAX_CANDIDATE_FILES} files`);
|
||||
}
|
||||
const canonicalFiles = [...manifest.files].sort((left, right) =>
|
||||
asciiCompare(left.path, right.path),
|
||||
);
|
||||
if (JSON.stringify(manifest.files) !== JSON.stringify(canonicalFiles)) {
|
||||
throw new Error("candidate manifest files are not in canonical ASCII order");
|
||||
}
|
||||
const expectedFiles = new Map<string, Readonly<{ bytes: number; sha256: string }>>();
|
||||
let declaredBytes = 0;
|
||||
for (const file of manifest.files) {
|
||||
assertSafeMemberPath(file.path);
|
||||
if (expectedFiles.has(file.path)) {
|
||||
throw new Error(`candidate manifest duplicate file: ${file.path}`);
|
||||
}
|
||||
declaredBytes += file.bytes;
|
||||
if (!Number.isSafeInteger(declaredBytes) || declaredBytes > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError("candidate manifest declared bytes exceed the archive bound");
|
||||
}
|
||||
expectedFiles.set(file.path, { bytes: file.bytes, sha256: file.sha256 });
|
||||
}
|
||||
const evidencePaths = [...expectedFiles.keys()]
|
||||
.filter((member) => !member.startsWith("dist/"))
|
||||
.sort(asciiCompare);
|
||||
if (
|
||||
JSON.stringify(evidencePaths) !==
|
||||
JSON.stringify([...RELEASE_CANDIDATE_EVIDENCE_PATHS].sort(asciiCompare))
|
||||
) {
|
||||
throw new Error("candidate manifest evidence member set drift");
|
||||
}
|
||||
const distFiles = manifest.files.filter(({ path: member }) => member.startsWith("dist/"));
|
||||
if (distFiles.length === 0) throw new Error("candidate manifest has no dist files");
|
||||
const lockfile = expectedFiles.get("pnpm-lock.yaml");
|
||||
if (!lockfile || lockfile.sha256 !== manifest.lockfileSha256) {
|
||||
throw new Error("candidate manifest lockfile digest summary mismatch");
|
||||
}
|
||||
if (
|
||||
distSha256(distFiles.map((file) => ({ ...file, gzipBytes: 0 }))) !==
|
||||
manifest.distSha256
|
||||
) {
|
||||
throw new Error("candidate manifest dist digest summary mismatch");
|
||||
}
|
||||
if (supplyChainDigest(manifest.files) !== manifest.bundleSha256) {
|
||||
throw new Error("candidate manifest bundle digest summary mismatch");
|
||||
}
|
||||
}
|
||||
|
||||
async function verifyExtractedTree(
|
||||
extractionRoot: string,
|
||||
preflightManifest: ReleaseCandidateManifest,
|
||||
): Promise<Readonly<{ memberCount: number; manifest: ReleaseCandidateManifest }>> {
|
||||
const entries = await walkExtractedTree(extractionRoot);
|
||||
if (entries.length === 0 || entries.length > MAX_ARCHIVE_MEMBERS) {
|
||||
throw new RangeError(`candidate archive member count is outside 1..${MAX_ARCHIVE_MEMBERS}`);
|
||||
}
|
||||
const manifest = releaseCandidateManifestSchema.parse(
|
||||
JSON.parse(
|
||||
await readFile(path.join(extractionRoot, RELEASE_CANDIDATE_MANIFEST_PATH), "utf8"),
|
||||
) as unknown,
|
||||
);
|
||||
if (JSON.stringify(manifest) !== JSON.stringify(preflightManifest)) {
|
||||
throw new Error("candidate manifest changed between preflight and extraction");
|
||||
}
|
||||
if (manifest.files.length === 0 || manifest.files.length > MAX_CANDIDATE_FILES) {
|
||||
throw new RangeError(`candidate manifest exceeds ${MAX_CANDIDATE_FILES} files`);
|
||||
}
|
||||
const canonicalFiles = [...manifest.files].sort((left, right) =>
|
||||
asciiCompare(left.path, right.path),
|
||||
);
|
||||
if (JSON.stringify(manifest.files) !== JSON.stringify(canonicalFiles)) {
|
||||
throw new Error("candidate manifest files are not in canonical ASCII order");
|
||||
}
|
||||
const expectedFiles = new Map<string, Readonly<{ bytes: number; sha256: string }>>();
|
||||
let declaredBytes = 0;
|
||||
for (const file of manifest.files) {
|
||||
assertSafeMemberPath(file.path);
|
||||
if (expectedFiles.has(file.path)) throw new Error(`candidate manifest duplicate file: ${file.path}`);
|
||||
declaredBytes += file.bytes;
|
||||
if (!Number.isSafeInteger(declaredBytes) || declaredBytes > MAX_ARCHIVE_BYTES) {
|
||||
throw new RangeError("candidate manifest declared bytes exceed the archive bound");
|
||||
}
|
||||
expectedFiles.set(file.path, { bytes: file.bytes, sha256: file.sha256 });
|
||||
}
|
||||
const evidencePaths = [...expectedFiles.keys()]
|
||||
.filter((member) => !member.startsWith("dist/"))
|
||||
.sort(asciiCompare);
|
||||
if (
|
||||
JSON.stringify(evidencePaths) !==
|
||||
JSON.stringify([...RELEASE_CANDIDATE_EVIDENCE_PATHS].sort(asciiCompare))
|
||||
) {
|
||||
throw new Error("candidate manifest evidence member set drift");
|
||||
}
|
||||
const distFiles = manifest.files.filter(({ path: member }) => member.startsWith("dist/"));
|
||||
if (distFiles.length === 0) throw new Error("candidate manifest has no dist files");
|
||||
const lockfile = expectedFiles.get("pnpm-lock.yaml");
|
||||
if (!lockfile || lockfile.sha256 !== manifest.lockfileSha256) {
|
||||
throw new Error("candidate manifest lockfile digest summary mismatch");
|
||||
}
|
||||
if (
|
||||
distSha256(distFiles.map((file) => ({ ...file, gzipBytes: 0 }))) !==
|
||||
manifest.distSha256
|
||||
) {
|
||||
throw new Error("candidate manifest dist digest summary mismatch");
|
||||
}
|
||||
if (supplyChainDigest(manifest.files) !== manifest.bundleSha256) {
|
||||
throw new Error("candidate manifest bundle digest summary mismatch");
|
||||
}
|
||||
|
||||
const expectedFilePaths = new Set([
|
||||
...expectedFiles.keys(),
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
]);
|
||||
const expectedDirectories = new Set(directoryAncestors([...expectedFilePaths]));
|
||||
for (const entry of entries) {
|
||||
assertSafeMemberPath(entry.path);
|
||||
if (entry.type === "directory") {
|
||||
if (!expectedDirectories.has(entry.path)) {
|
||||
throw new Error(`candidate archive contains unexpected directory: ${entry.path}`);
|
||||
}
|
||||
} else if (!expectedFilePaths.has(entry.path)) {
|
||||
throw new Error(`candidate archive contains unexpected file: ${entry.path}`);
|
||||
}
|
||||
}
|
||||
const actualFiles = new Set(
|
||||
entries.filter(({ type }) => type === "file").map(({ path: member }) => member),
|
||||
);
|
||||
for (const expected of expectedFilePaths) {
|
||||
if (!actualFiles.has(expected)) throw new Error(`candidate archive is missing file: ${expected}`);
|
||||
}
|
||||
for (const [member, expected] of expectedFiles) {
|
||||
const bytes = await readFile(path.join(extractionRoot, member));
|
||||
if (bytes.byteLength !== expected.bytes) {
|
||||
throw new Error(`candidate archive member size mismatch: ${member}`);
|
||||
}
|
||||
if (createHash("sha256").update(bytes).digest("hex") !== expected.sha256) {
|
||||
throw new Error(`candidate archive member digest mismatch: ${member}`);
|
||||
}
|
||||
}
|
||||
return Object.freeze({ memberCount: entries.length, manifest });
|
||||
}
|
||||
|
||||
async function walkExtractedTree(
|
||||
root: string,
|
||||
relativeDirectory = "",
|
||||
): Promise<ReadonlyArray<Readonly<{ path: string; type: "file" | "directory" }>>> {
|
||||
const children = await readdir(path.join(root, relativeDirectory), {
|
||||
withFileTypes: true,
|
||||
});
|
||||
const entries: Array<Readonly<{ path: string; type: "file" | "directory" }>> = [];
|
||||
for (const child of children.sort((left, right) => asciiCompare(left.name, right.name))) {
|
||||
const relative = relativeDirectory ? `${relativeDirectory}/${child.name}` : child.name;
|
||||
assertSafeMemberPath(relative);
|
||||
const metadata = await lstat(path.join(root, relative));
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new Error(`candidate archive contains non-regular member: ${relative}`);
|
||||
}
|
||||
if (metadata.isDirectory() && child.isDirectory()) {
|
||||
entries.push(Object.freeze({ path: relative, type: "directory" }));
|
||||
entries.push(...(await walkExtractedTree(root, relative)));
|
||||
} else if (metadata.isFile() && child.isFile()) {
|
||||
if (metadata.nlink !== 1) {
|
||||
throw new Error(`candidate archive contains hard-linked member: ${relative}`);
|
||||
}
|
||||
entries.push(Object.freeze({ path: relative, type: "file" }));
|
||||
} else {
|
||||
throw new Error(`candidate archive contains non-regular member: ${relative}`);
|
||||
}
|
||||
if (entries.length > MAX_ARCHIVE_MEMBERS) {
|
||||
throw new RangeError(`candidate archive exceeds ${MAX_ARCHIVE_MEMBERS} members`);
|
||||
}
|
||||
}
|
||||
return entries;
|
||||
}
|
||||
|
||||
function assertSameIdentity(
|
||||
before: Awaited<ReturnType<typeof lstat>>,
|
||||
after: Awaited<ReturnType<typeof lstat>>,
|
||||
): void {
|
||||
if (
|
||||
!after.isFile() ||
|
||||
before.dev !== after.dev ||
|
||||
before.ino !== after.ino ||
|
||||
before.size !== after.size
|
||||
) {
|
||||
throw new Error("candidate archive file identity changed");
|
||||
}
|
||||
}
|
||||
|
||||
async function readCapturedArchive(
|
||||
handle: FileHandle,
|
||||
expectedSize: number,
|
||||
): Promise<Buffer> {
|
||||
const captured = Buffer.allocUnsafe(expectedSize + 1);
|
||||
let offset = 0;
|
||||
while (offset < captured.byteLength) {
|
||||
const { bytesRead } = await handle.read(
|
||||
captured,
|
||||
offset,
|
||||
captured.byteLength - offset,
|
||||
offset,
|
||||
);
|
||||
if (bytesRead === 0) break;
|
||||
offset += bytesRead;
|
||||
}
|
||||
if (offset !== expectedSize) {
|
||||
throw new Error("candidate archive changed size during bounded capture");
|
||||
}
|
||||
return captured.subarray(0, offset);
|
||||
}
|
||||
|
||||
function readManifestFromArchive(archiveHandle: FileHandle): ReleaseCandidateManifest {
|
||||
const extracted = spawnSync(
|
||||
TAR_EXECUTABLE,
|
||||
[
|
||||
"--extract",
|
||||
"--gzip",
|
||||
"--to-stdout",
|
||||
"--file",
|
||||
"/proc/self/fd/3",
|
||||
"--",
|
||||
RELEASE_CANDIDATE_MANIFEST_PATH,
|
||||
],
|
||||
{
|
||||
maxBuffer: 8_388_609,
|
||||
timeout: 10_000,
|
||||
env: TAR_ENVIRONMENT,
|
||||
stdio: ["ignore", "pipe", "pipe", archiveHandle.fd],
|
||||
},
|
||||
);
|
||||
if (extracted.status !== 0 || extracted.signal || extracted.error) {
|
||||
throw new Error(
|
||||
`candidate manifest preflight failed: ${String(extracted.stderr) || extracted.error?.message || extracted.signal}`,
|
||||
);
|
||||
}
|
||||
const bytes = Buffer.from(extracted.stdout);
|
||||
if (bytes.byteLength === 0 || bytes.byteLength > 8_388_608) {
|
||||
throw new RangeError("candidate manifest preflight size is outside 1..8388608");
|
||||
}
|
||||
const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
|
||||
return releaseCandidateManifestSchema.parse(JSON.parse(source) as unknown);
|
||||
}
|
||||
|
||||
async function materializeCapturedArchive(
|
||||
archive: Buffer,
|
||||
): Promise<Readonly<{ root: string; handle: FileHandle }>> {
|
||||
const root = makePrivateTemporaryDirectory(path.join(tmpdir(), "ci-captured-archive-"));
|
||||
const file = path.join(root, "candidate.tar.gz");
|
||||
let handle: FileHandle | undefined;
|
||||
try {
|
||||
handle = await open(
|
||||
file,
|
||||
constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
// `open` subtracts the umask too. The extractor re-opens this file by
|
||||
// `/proc/self/fd/N` from a child process, and that re-open is a real
|
||||
// permission check, so a umask-zeroed mode makes `tar` fail to read the
|
||||
// candidate it was just handed.
|
||||
await handle.chmod(0o600);
|
||||
await handle.writeFile(archive);
|
||||
await handle.sync();
|
||||
await unlink(file);
|
||||
return Object.freeze({ root, handle });
|
||||
} catch (error) {
|
||||
if (handle) await handle.close().catch(() => undefined);
|
||||
await rm(root, { recursive: true, force: true });
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function assertSafeMemberPath(member: string): void {
|
||||
if (
|
||||
!member ||
|
||||
member.startsWith("-") ||
|
||||
Buffer.byteLength(member, "utf8") > MAX_MEMBER_PATH_BYTES ||
|
||||
member.includes("\\") ||
|
||||
[...member].some((character) => {
|
||||
const codePoint = character.codePointAt(0)!;
|
||||
return codePoint <= 0x1f || codePoint === 0x7f;
|
||||
}) ||
|
||||
path.posix.isAbsolute(member) ||
|
||||
path.posix.normalize(member) !== member ||
|
||||
member === ".." ||
|
||||
member.startsWith("../") ||
|
||||
member.includes("/../")
|
||||
) {
|
||||
throw new TypeError(`candidate archive contains unsafe member path: ${member}`);
|
||||
}
|
||||
}
|
||||
|
||||
function directoryAncestors(files: readonly string[]): string[] {
|
||||
const directories = new Set<string>();
|
||||
for (const file of files) {
|
||||
let directory = path.posix.dirname(file);
|
||||
while (directory !== ".") {
|
||||
directories.add(directory);
|
||||
directory = path.posix.dirname(directory);
|
||||
}
|
||||
}
|
||||
return [...directories];
|
||||
}
|
||||
|
||||
function asciiCompare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
|
||||
async function pathExists(target: string): Promise<boolean> {
|
||||
try {
|
||||
await lstat(target);
|
||||
return true;
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return false;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
import { z } from "zod";
|
||||
|
||||
export const ciContractReportSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(2),
|
||||
nodeVersion: z.string().regex(/^\d+\.\d+\.\d+$/u),
|
||||
gateCount: z.literal(27),
|
||||
commandDefinitionCount: z.number().int().positive(),
|
||||
commandReferenceCount: z.number().int().positive(),
|
||||
artifactCount: z.number().int().positive(),
|
||||
jobCount: z.literal(9),
|
||||
workflowSha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
durationStatus: z.string().min(1),
|
||||
negativeFixtures: z.array(
|
||||
z
|
||||
.object({
|
||||
readiness: z.enum([
|
||||
"MERGE_READY",
|
||||
"RELEASE_READY",
|
||||
"PROD_PROMOTION_READY",
|
||||
"FIELD_SLO_READY",
|
||||
"DOCUMENTATION_READY",
|
||||
]),
|
||||
failedGate: z.string().regex(/^FE-GATE-\d{3}$/u),
|
||||
passed: z.boolean(),
|
||||
})
|
||||
.strict(),
|
||||
),
|
||||
failures: z.array(z.string()),
|
||||
passed: z.boolean(),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((report, context) => {
|
||||
const fail = (path: PropertyKey[], message: string) =>
|
||||
context.addIssue({ code: "custom", path, message });
|
||||
if ((report.passed === true) !== (report.failures.length === 0)) {
|
||||
fail(["passed"], "passed must agree with failures");
|
||||
}
|
||||
if (
|
||||
report.negativeFixtures.length !== 5 ||
|
||||
report.negativeFixtures.some((fixture) => !fixture.passed)
|
||||
) {
|
||||
fail(["negativeFixtures"], "every readiness negative fixture must pass");
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,187 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
|
||||
export async function writeCiGateLogAtomic(input: Readonly<{
|
||||
root: string;
|
||||
relativePath: string;
|
||||
content: string;
|
||||
maxBytes?: number;
|
||||
}>): Promise<void> {
|
||||
const root = path.resolve(input.root);
|
||||
const relative = normalizeRepositoryRelativePath(input.relativePath, "CI gate log path");
|
||||
const target = path.join(root, relative);
|
||||
const maxBytes = input.maxBytes ?? 67_108_864;
|
||||
const contentBytes = Buffer.byteLength(input.content, "utf8");
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || contentBytes < 1 || contentBytes > maxBytes) {
|
||||
throw new RangeError(`CI gate log size is outside 1..${maxBytes}: ${relative}`);
|
||||
}
|
||||
const parentIdentity = await ensureSafePublishDirectory(root, path.dirname(target));
|
||||
await assertSafePublishLeaf(target, relative);
|
||||
const temporary = path.join(
|
||||
path.dirname(target),
|
||||
`.${path.basename(target)}.${randomUUID()}.tmp`,
|
||||
);
|
||||
let ownsTemporary = false;
|
||||
try {
|
||||
const handle = await open(
|
||||
temporary,
|
||||
constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
||||
0o644,
|
||||
);
|
||||
ownsTemporary = true;
|
||||
let failure: unknown;
|
||||
try {
|
||||
await handle.writeFile(input.content, "utf8");
|
||||
await handle.sync();
|
||||
} catch (error) {
|
||||
failure = error;
|
||||
}
|
||||
try {
|
||||
await handle.close();
|
||||
} catch (error) {
|
||||
failure ??= error;
|
||||
}
|
||||
if (failure) throw failure;
|
||||
await assertDirectoryIdentity(path.dirname(target), parentIdentity, relative);
|
||||
await assertSafePublishLeaf(target, relative);
|
||||
await rename(temporary, target);
|
||||
ownsTemporary = false;
|
||||
const directory = await open(path.dirname(target), constants.O_RDONLY);
|
||||
try {
|
||||
try {
|
||||
await directory.sync();
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "EINVAL") && !hasErrorCode(error, "ENOTSUP")) throw error;
|
||||
}
|
||||
} finally {
|
||||
await directory.close();
|
||||
}
|
||||
} catch (error) {
|
||||
if (ownsTemporary) {
|
||||
try {
|
||||
await rm(temporary, { force: true });
|
||||
} catch {
|
||||
// Preserve the publication failure and clean only the owned sibling temp.
|
||||
}
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
export async function ensureSafePublishDirectory(
|
||||
rootInput: string,
|
||||
directoryInput: string,
|
||||
): Promise<Stats> {
|
||||
const root = path.resolve(rootInput);
|
||||
const directory = path.resolve(directoryInput);
|
||||
const relativeDirectory = path.relative(root, directory);
|
||||
if (
|
||||
relativeDirectory === ".." ||
|
||||
relativeDirectory.startsWith(`..${path.sep}`) ||
|
||||
path.isAbsolute(relativeDirectory)
|
||||
) {
|
||||
throw new TypeError("CI publish directory escapes root");
|
||||
}
|
||||
const rootMetadata = await lstat(root);
|
||||
if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
|
||||
throw new TypeError("CI gate log root is unsafe");
|
||||
}
|
||||
let ancestor = root;
|
||||
for (const segment of relativeDirectory.split(path.sep).filter(Boolean)) {
|
||||
ancestor = path.join(ancestor, segment);
|
||||
let metadata;
|
||||
try {
|
||||
metadata = await lstat(ancestor);
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
try {
|
||||
await mkdir(ancestor);
|
||||
} catch (mkdirError) {
|
||||
if (!hasErrorCode(mkdirError, "EEXIST")) throw mkdirError;
|
||||
}
|
||||
metadata = await lstat(ancestor);
|
||||
}
|
||||
if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
|
||||
throw new TypeError(`CI publish ancestor is unsafe: ${relativeDirectory}`);
|
||||
}
|
||||
}
|
||||
return lstat(directory);
|
||||
}
|
||||
|
||||
export async function assertSafePublishLeaf(
|
||||
target: string,
|
||||
label = target,
|
||||
): Promise<void> {
|
||||
try {
|
||||
const metadata = await lstat(target);
|
||||
if (metadata.isSymbolicLink() || !metadata.isFile()) {
|
||||
throw new TypeError(`CI publish leaf is unsafe: ${label}`);
|
||||
}
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
}
|
||||
}
|
||||
|
||||
export async function assertSafeExistingPublishPath(
|
||||
rootInput: string,
|
||||
targetInput: string,
|
||||
): Promise<boolean> {
|
||||
const root = path.resolve(rootInput);
|
||||
const target = path.resolve(targetInput);
|
||||
const relative = path.relative(root, target);
|
||||
if (
|
||||
relative === "" ||
|
||||
relative === ".." ||
|
||||
relative.startsWith(`..${path.sep}`) ||
|
||||
path.isAbsolute(relative)
|
||||
) {
|
||||
throw new TypeError("CI publish target escapes root");
|
||||
}
|
||||
const rootMetadata = await lstat(root);
|
||||
if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
|
||||
throw new TypeError("CI publish root is unsafe");
|
||||
}
|
||||
const segments = relative.split(path.sep).filter(Boolean);
|
||||
let current = root;
|
||||
for (const [index, segment] of segments.entries()) {
|
||||
current = path.join(current, segment);
|
||||
let metadata: Stats;
|
||||
try {
|
||||
metadata = await lstat(current);
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return false;
|
||||
throw error;
|
||||
}
|
||||
const leaf = index === segments.length - 1;
|
||||
if (metadata.isSymbolicLink() || (leaf ? !metadata.isFile() : !metadata.isDirectory())) {
|
||||
throw new TypeError(`CI publish path is unsafe: ${relative}`);
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
async function assertDirectoryIdentity(
|
||||
directory: string,
|
||||
expected: Stats,
|
||||
label: string,
|
||||
): Promise<void> {
|
||||
const actual = await lstat(directory);
|
||||
if (
|
||||
actual.isSymbolicLink() ||
|
||||
!actual.isDirectory() ||
|
||||
expected.dev <= 0 ||
|
||||
expected.ino <= 0 ||
|
||||
actual.dev !== expected.dev ||
|
||||
actual.ino !== expected.ino
|
||||
) {
|
||||
throw new TypeError(`CI publish directory identity changed: ${label}`);
|
||||
}
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
export type GateStepExpectation =
|
||||
| Readonly<{ kind: "pass" }>
|
||||
| Readonly<{
|
||||
kind: "fail";
|
||||
expectedExitCode: number;
|
||||
expectedDiagnosticId: string;
|
||||
}>;
|
||||
|
||||
export type GateProcessResult = Readonly<{
|
||||
status: number | null;
|
||||
signal: string | null;
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
error?: Readonly<{ code?: string }>;
|
||||
}>;
|
||||
|
||||
export type GateStepClassification =
|
||||
| Readonly<{
|
||||
kind: "EXPECTED_PASS" | "EXPECTED_FAILURE";
|
||||
expectationMet: true;
|
||||
}>
|
||||
| Readonly<{
|
||||
kind: "UNEXPECTED_EXIT";
|
||||
expectationMet: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
kind: "UNEXPECTED_DIAGNOSTIC";
|
||||
expectationMet: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
kind: "INFRASTRUCTURE_FAILURE";
|
||||
expectationMet: false;
|
||||
detail: string;
|
||||
}>;
|
||||
|
||||
/** A negative fixture passes only with its registered exit and diagnostic. */
|
||||
export function classifyGateStepResult(
|
||||
expectation: GateStepExpectation,
|
||||
result: GateProcessResult,
|
||||
): GateStepClassification {
|
||||
const errorCode = result.error?.code;
|
||||
const spawnFailed = result.error !== undefined;
|
||||
if (spawnFailed || result.signal || result.status === null) {
|
||||
return Object.freeze({
|
||||
kind: "INFRASTRUCTURE_FAILURE" as const,
|
||||
expectationMet: false as const,
|
||||
detail:
|
||||
errorCode ??
|
||||
result.signal ??
|
||||
(spawnFailed ? "SPAWN_ERROR" : "NO_EXIT_STATUS"),
|
||||
});
|
||||
}
|
||||
if (expectation.kind === "pass" && result.status === 0) {
|
||||
return Object.freeze({
|
||||
kind: "EXPECTED_PASS" as const,
|
||||
expectationMet: true as const,
|
||||
});
|
||||
}
|
||||
if (expectation.kind === "fail") {
|
||||
if (result.status !== expectation.expectedExitCode) {
|
||||
return Object.freeze({
|
||||
kind: "UNEXPECTED_EXIT" as const,
|
||||
expectationMet: false as const,
|
||||
});
|
||||
}
|
||||
const diagnosticOutput = `${result.stdout}\n${result.stderr}`;
|
||||
if (!diagnosticOutput.includes(expectation.expectedDiagnosticId)) {
|
||||
return Object.freeze({
|
||||
kind: "UNEXPECTED_DIAGNOSTIC" as const,
|
||||
expectationMet: false as const,
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
kind: "EXPECTED_FAILURE" as const,
|
||||
expectationMet: true as const,
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
kind: "UNEXPECTED_EXIT" as const,
|
||||
expectationMet: false as const,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
type ViteManifestEntry = Readonly<{
|
||||
file: string;
|
||||
isEntry?: boolean;
|
||||
imports?: readonly string[];
|
||||
}>;
|
||||
|
||||
/**
|
||||
* Static imports of an entry are part of initial JavaScript. Every remaining
|
||||
* JavaScript output is governed by the lazy-chunk budget.
|
||||
*
|
||||
*/
|
||||
export function classifyViteJavascript(
|
||||
manifest: Readonly<Record<string, ViteManifestEntry>>,
|
||||
) {
|
||||
const initialFiles = new Set<string>();
|
||||
const visitedKeys = new Set<string>();
|
||||
const pendingKeys = Object.entries(manifest)
|
||||
.filter(([, entry]) => entry.isEntry)
|
||||
.map(([key]) => key);
|
||||
const missingImports: string[] = [];
|
||||
|
||||
while (pendingKeys.length > 0) {
|
||||
const key = pendingKeys.pop();
|
||||
if (key === undefined) break;
|
||||
if (visitedKeys.has(key)) continue;
|
||||
visitedKeys.add(key);
|
||||
const entry = manifest[key];
|
||||
if (!entry) {
|
||||
missingImports.push(key);
|
||||
continue;
|
||||
}
|
||||
if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
|
||||
pendingKeys.push(...(entry.imports ?? []));
|
||||
}
|
||||
|
||||
const allJavaScript = new Set(
|
||||
Object.values(manifest)
|
||||
.map((entry) => entry.file)
|
||||
.filter((file) => file.endsWith(".js")),
|
||||
);
|
||||
const lazyFiles = [...allJavaScript].filter(
|
||||
(file) => !initialFiles.has(file),
|
||||
);
|
||||
return Object.freeze({
|
||||
initialFiles: Object.freeze([...initialFiles].sort()),
|
||||
lazyFiles: Object.freeze(lazyFiles.sort()),
|
||||
missingImports: Object.freeze(missingImports.sort()),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,353 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
PROMOTED_FILE_NAMES,
|
||||
type PromotedFileName,
|
||||
} from "../contracts/promotion-artifacts.ts";
|
||||
import {
|
||||
PROMOTION_VERIFIER_ID,
|
||||
PROMOTION_VERIFIER_VERSION,
|
||||
assertDistinctProviderTrust,
|
||||
evaluatePromotionEvidence,
|
||||
providerVerificationArtifactSchema,
|
||||
provenanceProviderAttestationSchema,
|
||||
vulnerabilityProviderReportSchema,
|
||||
trustPolicySha256,
|
||||
type ProviderTrust,
|
||||
} from "./provider-evidence.ts";
|
||||
import { verifyCapturedCiCandidateArchive } from "./ci-candidate-archive.ts";
|
||||
import { LOCAL_EVIDENCE_ASSESSMENT_PATH } from "./release-candidate.ts";
|
||||
import { verifyArchivedLocalEvidence } from "./local-release-evidence.ts";
|
||||
|
||||
export type ExactPromotionBundle = Readonly<
|
||||
Partial<Record<PromotedFileName, Buffer>>
|
||||
>;
|
||||
|
||||
export type ExactPromotionExpectedContext = Readonly<{
|
||||
run: Readonly<{ id: string; attempt: number }>;
|
||||
sourceRevision: string;
|
||||
archiveSha256: string;
|
||||
sourceSetSha256?: string;
|
||||
bundleSha256?: string;
|
||||
distSha256?: string;
|
||||
lockfileSha256?: string;
|
||||
}>;
|
||||
|
||||
export async function verifyExactPromotionBundle(
|
||||
files: ExactPromotionBundle,
|
||||
options: Readonly<{
|
||||
vulnerabilityTrust: ProviderTrust;
|
||||
provenanceTrust: ProviderTrust;
|
||||
expected: ExactPromotionExpectedContext;
|
||||
nowEpochMs?: () => number;
|
||||
}>,
|
||||
): Promise<Readonly<{ status: "PASS" }>> {
|
||||
assertDistinctProviderTrust(options);
|
||||
assertExternalExpectedContext(options.expected);
|
||||
const names = Object.keys(files).sort(asciiCompare);
|
||||
const expectedNames = [...PROMOTED_FILE_NAMES].sort(asciiCompare);
|
||||
if (JSON.stringify(names) !== JSON.stringify(expectedNames)) {
|
||||
throw new Error("promotion bundle must contain the exact five canonical files");
|
||||
}
|
||||
for (const name of PROMOTED_FILE_NAMES) {
|
||||
if (!Buffer.isBuffer(files[name])) {
|
||||
throw new TypeError(`promotion bundle file is missing or not captured bytes: ${name}`);
|
||||
}
|
||||
}
|
||||
|
||||
const archiveBytes = files["release-candidate.tar.gz"]!;
|
||||
const vulnerabilityBytes = files["vulnerability-report.json"]!;
|
||||
const provenanceBytes = files["provenance-attestation.json"]!;
|
||||
const providerBytes = files["provider-verification.json"]!;
|
||||
const promotionBytes = files["promotion-verification.json"]!;
|
||||
const vulnerability = vulnerabilityProviderReportSchema.parse(parseJson(
|
||||
vulnerabilityBytes,
|
||||
"vulnerability report",
|
||||
));
|
||||
const provenance = provenanceProviderAttestationSchema.parse(parseJson(
|
||||
provenanceBytes,
|
||||
"provenance attestation",
|
||||
));
|
||||
const provider = providerVerificationArtifactSchema.parse(parseJson(
|
||||
providerBytes,
|
||||
"provider verification",
|
||||
));
|
||||
const promotion = providerVerificationArtifactSchema.parse(parseJson(
|
||||
promotionBytes,
|
||||
"promotion verification",
|
||||
));
|
||||
|
||||
if (
|
||||
provider.artifactType !== "provider-verification" ||
|
||||
promotion.artifactType !== "promotion-verification"
|
||||
) {
|
||||
throw new Error("promotion verification artifact role mismatch");
|
||||
}
|
||||
for (const [label, record] of [
|
||||
["provider", provider],
|
||||
["promotion", promotion],
|
||||
] as const) {
|
||||
if (
|
||||
record.verifier.id !== PROMOTION_VERIFIER_ID ||
|
||||
record.verifier.version !== PROMOTION_VERIFIER_VERSION
|
||||
) {
|
||||
throw new Error(`${label} verification literal verifier identity mismatch`);
|
||||
}
|
||||
if (record.status !== "PASS" || record.failures.length !== 0) {
|
||||
throw new Error(`${label} verification must be PASS without failures`);
|
||||
}
|
||||
}
|
||||
if (
|
||||
provider.vulnerabilityStatus !== "PASS" ||
|
||||
provider.provenanceAttestationStatus !== "PASS"
|
||||
) {
|
||||
throw new Error("provider verification subordinate statuses must both be PASS");
|
||||
}
|
||||
if (promotion.localEvidenceStatus !== "PASS") {
|
||||
throw new Error("promotion local evidence subordinate status must be PASS");
|
||||
}
|
||||
|
||||
assertEqual("shared verifiedAt", provider.verifiedAt, promotion.verifiedAt);
|
||||
assertEqual("shared run", provider.run, promotion.run);
|
||||
assertEqual("shared source", provider.source, promotion.source);
|
||||
assertEqual("shared candidate", provider.candidate, promotion.candidate);
|
||||
assertEqual(
|
||||
"shared provider evidence",
|
||||
provider.providerEvidence,
|
||||
promotion.providerEvidence,
|
||||
);
|
||||
assertEqual(
|
||||
"shared trust policy",
|
||||
provider.trustPolicySha256,
|
||||
promotion.trustPolicySha256,
|
||||
);
|
||||
assertEqual("external expected run", provider.run, options.expected.run);
|
||||
assertEqual(
|
||||
"external expected source revision",
|
||||
provider.source.revision,
|
||||
options.expected.sourceRevision,
|
||||
);
|
||||
assertEqual(
|
||||
"external expected archive digest",
|
||||
provider.candidate.archiveSha256,
|
||||
options.expected.archiveSha256,
|
||||
);
|
||||
for (const [label, actual, expected] of [
|
||||
["source set", provider.source.sourceSetSha256, options.expected.sourceSetSha256],
|
||||
["bundle", provider.candidate.bundleSha256, options.expected.bundleSha256],
|
||||
["dist", provider.candidate.distSha256, options.expected.distSha256],
|
||||
["lockfile", provider.candidate.lockfileSha256, options.expected.lockfileSha256],
|
||||
] as const) {
|
||||
if (expected !== undefined) {
|
||||
assertEqual(`external expected ${label} digest`, actual, expected);
|
||||
}
|
||||
}
|
||||
const anchoredTrustPolicySha256 = trustPolicySha256(options);
|
||||
if (provider.trustPolicySha256 !== anchoredTrustPolicySha256) {
|
||||
throw new Error("verification trust policy does not match anchored provider keys");
|
||||
}
|
||||
|
||||
if (promotion.providerVerificationSha256 !== sha256(providerBytes)) {
|
||||
throw new Error("promotion provider verification byte hash mismatch");
|
||||
}
|
||||
if (
|
||||
provider.candidate.archiveSha256 !== sha256(archiveBytes) ||
|
||||
provider.providerEvidence.vulnerabilityReportSha256 !== sha256(vulnerabilityBytes) ||
|
||||
provider.providerEvidence.provenanceAttestationSha256 !== sha256(provenanceBytes)
|
||||
) {
|
||||
if (provider.candidate.archiveSha256 !== sha256(archiveBytes)) {
|
||||
throw new Error("candidate archive actual digest mismatch");
|
||||
}
|
||||
if (
|
||||
provider.providerEvidence.vulnerabilityReportSha256 !==
|
||||
sha256(vulnerabilityBytes)
|
||||
) {
|
||||
throw new Error("vulnerability report actual digest mismatch");
|
||||
}
|
||||
throw new Error("provenance attestation actual digest mismatch");
|
||||
}
|
||||
|
||||
for (const [label, evidence, nonce, keyId, fingerprint] of [
|
||||
[
|
||||
"vulnerability",
|
||||
vulnerability,
|
||||
provider.providerEvidence.vulnerabilityInvocationNonce,
|
||||
provider.providerEvidence.vulnerabilityKeyId,
|
||||
provider.providerEvidence.vulnerabilityKeyFingerprint,
|
||||
],
|
||||
[
|
||||
"provenance",
|
||||
provenance,
|
||||
provider.providerEvidence.provenanceInvocationNonce,
|
||||
provider.providerEvidence.provenanceKeyId,
|
||||
provider.providerEvidence.provenanceKeyFingerprint,
|
||||
],
|
||||
] as const) {
|
||||
assertEqual(`${label} run`, { id: evidence.run.id, attempt: evidence.run.attempt }, provider.run);
|
||||
assertEqual(`${label} source`, evidence.source, provider.source);
|
||||
assertEqual(`${label} candidate`, evidence.candidate, provider.candidate);
|
||||
if (
|
||||
evidence.run.invocationNonce !== nonce ||
|
||||
evidence.signature.keyId !== keyId ||
|
||||
evidence.signature.publicKeyFingerprint !== fingerprint
|
||||
) {
|
||||
throw new Error(`${label} provider evidence nonce or trust role mismatch`);
|
||||
}
|
||||
}
|
||||
if (provenance.subject.digest.sha256 !== provider.candidate.distSha256) {
|
||||
throw new Error("provenance subject dist digest mismatch");
|
||||
}
|
||||
if (vulnerability.findings.length !== 0) {
|
||||
throw new Error("vulnerability report is not PASS");
|
||||
}
|
||||
assertEqual(
|
||||
"signed secret scan attestation",
|
||||
vulnerability.secretScanAttestation,
|
||||
provider.providerEvidence.secretScanAttestation,
|
||||
);
|
||||
|
||||
let assessmentSha256: string | null = null;
|
||||
const localIdentityHolder: {
|
||||
current: null | Readonly<{
|
||||
sourceRevision: string;
|
||||
sourceSetSha256: string;
|
||||
assessmentSha256: string;
|
||||
secretScan: Readonly<{
|
||||
policySha256: string;
|
||||
sarifSha256: string;
|
||||
scanInputSha256: string;
|
||||
}>;
|
||||
}>;
|
||||
} = { current: null };
|
||||
await verifyCapturedCiCandidateArchive(
|
||||
archiveBytes,
|
||||
provider.candidate.archiveSha256,
|
||||
{
|
||||
verifyExtracted: async (extractionRoot, manifest) => {
|
||||
assertEqual("archive candidate", {
|
||||
bundleSha256: manifest.bundleSha256,
|
||||
distSha256: manifest.distSha256,
|
||||
lockfileSha256: manifest.lockfileSha256,
|
||||
}, {
|
||||
bundleSha256: provider.candidate.bundleSha256,
|
||||
distSha256: provider.candidate.distSha256,
|
||||
lockfileSha256: provider.candidate.lockfileSha256,
|
||||
});
|
||||
assessmentSha256 = sha256(
|
||||
await readFile(path.join(extractionRoot, LOCAL_EVIDENCE_ASSESSMENT_PATH)),
|
||||
);
|
||||
const local = await verifyArchivedLocalEvidence({
|
||||
extractionRoot,
|
||||
expectedManifest: manifest,
|
||||
});
|
||||
if (local.status !== "PASS" || !local.identity) {
|
||||
throw new Error(
|
||||
`exact-five archived local verification is not PASS: ${local.failures.join(", ")}`,
|
||||
);
|
||||
}
|
||||
localIdentityHolder.current = local.identity;
|
||||
},
|
||||
},
|
||||
);
|
||||
if (assessmentSha256 !== promotion.localEvidenceAssessmentSha256) {
|
||||
throw new Error("promotion local evidence assessment actual digest mismatch");
|
||||
}
|
||||
if (
|
||||
!localIdentityHolder.current ||
|
||||
localIdentityHolder.current.sourceRevision !== provider.source.revision ||
|
||||
localIdentityHolder.current.sourceSetSha256 !== provider.source.sourceSetSha256 ||
|
||||
localIdentityHolder.current.assessmentSha256 !== promotion.localEvidenceAssessmentSha256
|
||||
) {
|
||||
throw new Error("exact-five archived local identity mismatch");
|
||||
}
|
||||
assertEqual("archived secret scan attestation", {
|
||||
status: "PASS",
|
||||
localEvidenceAssessmentSha256: localIdentityHolder.current.assessmentSha256,
|
||||
sourceSetSha256: localIdentityHolder.current.sourceSetSha256,
|
||||
policySha256: localIdentityHolder.current.secretScan.policySha256,
|
||||
sarifSha256: localIdentityHolder.current.secretScan.sarifSha256,
|
||||
scanInputSha256: localIdentityHolder.current.secretScan.scanInputSha256,
|
||||
}, vulnerability.secretScanAttestation);
|
||||
const reevaluated = evaluatePromotionEvidence({
|
||||
expected: {
|
||||
run: provider.run,
|
||||
source: provider.source,
|
||||
candidate: provider.candidate,
|
||||
vulnerabilityInvocationNonce:
|
||||
provider.providerEvidence.vulnerabilityInvocationNonce,
|
||||
provenanceInvocationNonce:
|
||||
provider.providerEvidence.provenanceInvocationNonce,
|
||||
secretScanAttestation: provider.providerEvidence.secretScanAttestation,
|
||||
},
|
||||
localStatus: "PASS",
|
||||
vulnerabilityReport: vulnerability,
|
||||
provenanceAttestation: provenance,
|
||||
vulnerabilityTrust: options.vulnerabilityTrust,
|
||||
provenanceTrust: options.provenanceTrust,
|
||||
nowEpochMs: options.nowEpochMs,
|
||||
});
|
||||
if (
|
||||
reevaluated.status !== "PASS" ||
|
||||
reevaluated.vulnerabilityStatus !== "PASS" ||
|
||||
reevaluated.provenanceAttestationStatus !== "PASS"
|
||||
) {
|
||||
throw new Error(
|
||||
`exact-five provider signature/freshness revalidation is not PASS: ${reevaluated.failures.join(", ")}`,
|
||||
);
|
||||
}
|
||||
return Object.freeze({ status: "PASS" as const });
|
||||
}
|
||||
|
||||
function assertExternalExpectedContext(
|
||||
expected: ExactPromotionExpectedContext,
|
||||
): void {
|
||||
if (
|
||||
!expected ||
|
||||
typeof expected.run?.id !== "string" ||
|
||||
expected.run.id.length === 0 ||
|
||||
!Number.isSafeInteger(expected.run.attempt) ||
|
||||
expected.run.attempt < 1 ||
|
||||
!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(expected.sourceRevision) ||
|
||||
!isSha256(expected.archiveSha256)
|
||||
) {
|
||||
throw new TypeError("external expected promotion context is invalid or incomplete");
|
||||
}
|
||||
for (const digest of [
|
||||
expected.sourceSetSha256,
|
||||
expected.bundleSha256,
|
||||
expected.distSha256,
|
||||
expected.lockfileSha256,
|
||||
]) {
|
||||
if (digest !== undefined && !isSha256(digest)) {
|
||||
throw new TypeError("external optional expected promotion digest is invalid");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function isSha256(value: unknown): value is string {
|
||||
return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
|
||||
}
|
||||
|
||||
function parseJson(bytes: Buffer, label: string): unknown {
|
||||
try {
|
||||
return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as unknown;
|
||||
} catch {
|
||||
throw new TypeError(`${label} is not strict UTF-8 JSON`);
|
||||
}
|
||||
}
|
||||
|
||||
function assertEqual(label: string, left: unknown, right: unknown): void {
|
||||
if (JSON.stringify(left) !== JSON.stringify(right)) {
|
||||
throw new Error(`${label} mismatch`);
|
||||
}
|
||||
}
|
||||
|
||||
function sha256(bytes: Buffer): string {
|
||||
return createHash("sha256").update(bytes).digest("hex");
|
||||
}
|
||||
|
||||
function asciiCompare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
import { z } from "zod";
|
||||
|
||||
const WINDOW_MILLISECONDS = 28 * 24 * 60 * 60 * 1000;
|
||||
const nonEmptyString = z.string().trim().min(1);
|
||||
const timestamp = nonEmptyString.refine(
|
||||
(value) => Number.isFinite(Date.parse(value)),
|
||||
"must be an RFC 3339 timestamp",
|
||||
);
|
||||
const sampleSchema = z
|
||||
.object({
|
||||
timestamp,
|
||||
consent: z.boolean(),
|
||||
releaseId: nonEmptyString,
|
||||
routeId: nonEmptyString.regex(/^[A-Z][A-Z0-9_]*$/),
|
||||
lcpMs: z.number().finite().nonnegative(),
|
||||
cls: z.number().finite().nonnegative(),
|
||||
inpMs: z.number().finite().nonnegative(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const fieldEvidenceInputSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
environment: z.literal("production"),
|
||||
releaseId: nonEmptyString.refine(
|
||||
(value) => value !== "local-release",
|
||||
"must identify an immutable production release",
|
||||
),
|
||||
source: z
|
||||
.object({
|
||||
system: nonEmptyString,
|
||||
exportId: nonEmptyString,
|
||||
})
|
||||
.strict(),
|
||||
privacy: z
|
||||
.object({
|
||||
approved: z.literal(true),
|
||||
approvalRef: nonEmptyString,
|
||||
})
|
||||
.strict(),
|
||||
window: z
|
||||
.object({
|
||||
start: timestamp,
|
||||
end: timestamp,
|
||||
})
|
||||
.strict(),
|
||||
thresholdDecision: z
|
||||
.object({
|
||||
status: z.literal("approved"),
|
||||
minimumEligibleSamples: z.number().int().positive(),
|
||||
owner: nonEmptyString,
|
||||
reviewedAt: timestamp,
|
||||
evidenceRef: nonEmptyString,
|
||||
})
|
||||
.strict(),
|
||||
samples: z.array(sampleSchema),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((input, context) => {
|
||||
const start = Date.parse(input.window.start);
|
||||
const end = Date.parse(input.window.end);
|
||||
if (end - start !== WINDOW_MILLISECONDS) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["window"],
|
||||
message: "must cover exactly 28 days",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
export function validateFieldEvidenceInput(
|
||||
input: unknown,
|
||||
configuredMinimum: string | undefined,
|
||||
now: Date = new Date(),
|
||||
) {
|
||||
const parsed = fieldEvidenceInputSchema.safeParse(input);
|
||||
const failures = parsed.success
|
||||
? []
|
||||
: parsed.error.issues.map(
|
||||
(issue) => `${issue.path.join(".") || "input"}: ${issue.message}`,
|
||||
);
|
||||
const minimumEligibleSamples = Number(configuredMinimum);
|
||||
if (
|
||||
configuredMinimum === undefined ||
|
||||
!Number.isInteger(minimumEligibleSamples) ||
|
||||
minimumEligibleSamples <= 0
|
||||
) {
|
||||
failures.push("MIN_ELIGIBLE_SAMPLES: must be a positive integer");
|
||||
}
|
||||
|
||||
if (parsed.success) {
|
||||
if (
|
||||
parsed.data.thresholdDecision.minimumEligibleSamples !==
|
||||
minimumEligibleSamples
|
||||
) {
|
||||
failures.push(
|
||||
"MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
|
||||
);
|
||||
}
|
||||
if (Date.parse(parsed.data.window.end) > now.getTime()) {
|
||||
failures.push("window.end: must not be in the future");
|
||||
}
|
||||
if (Date.parse(parsed.data.thresholdDecision.reviewedAt) > now.getTime()) {
|
||||
failures.push("thresholdDecision.reviewedAt: must not be in the future");
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
data: parsed.success ? parsed.data : null,
|
||||
failures: Object.freeze(failures),
|
||||
minimumEligibleSamples:
|
||||
Number.isInteger(minimumEligibleSamples) && minimumEligibleSamples > 0
|
||||
? minimumEligibleSamples
|
||||
: null,
|
||||
passed: parsed.success && failures.length === 0,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
import { lstat, mkdir, readdir, symlink } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
/**
|
||||
* Links the repository's installed dependencies into a throwaway fixture root.
|
||||
*
|
||||
* The obvious form — one directory symlink at `<fixture>/node_modules` — is
|
||||
* destructive. A fixture runs `pnpm` inside itself, pnpm does not recognise the
|
||||
* modules directory it finds there, and its purge follows the symlink and
|
||||
* deletes the *repository's* real dependencies mid-run. With `CI=true` that
|
||||
* happens without a prompt, so a test suite silently uninstalls the workspace
|
||||
* it is running in.
|
||||
*
|
||||
* `node_modules` is therefore a real directory here, and every entry inside it
|
||||
* is an individual symlink. Package resolution is unchanged, but a recursive
|
||||
* delete unlinks the fixture's own symlinks instead of walking through one link
|
||||
* into the shared tree.
|
||||
*/
|
||||
export async function linkFixtureNodeModules(
|
||||
fixtureRoot: string,
|
||||
sourceRoot: string = process.cwd(),
|
||||
): Promise<void> {
|
||||
const source = path.join(sourceRoot, "node_modules");
|
||||
const target = path.join(fixtureRoot, "node_modules");
|
||||
await mkdir(target, { recursive: true });
|
||||
for (const entry of await readdir(source)) {
|
||||
const from = path.join(source, entry);
|
||||
const stats = await lstat(from);
|
||||
await symlink(from, path.join(target, entry), stats.isDirectory() ? "dir" : "file");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
|
||||
|
||||
/**
|
||||
* A release gate must not promote a local preview server as live hosting
|
||||
* evidence.
|
||||
*
|
||||
*/
|
||||
export function classifyLiveHostingBaseUrl(value: string):
|
||||
| {
|
||||
passed: true;
|
||||
reason: null;
|
||||
url: URL;
|
||||
observedOrigin: string;
|
||||
}
|
||||
| {
|
||||
passed: false;
|
||||
reason: string;
|
||||
url: URL | null;
|
||||
observedOrigin: string | null;
|
||||
} {
|
||||
let url: 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,281 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
export type AttemptStatus = number | "NETWORK_REJECTION" | "PENDING_ABORT";
|
||||
export type RetryReason = "NETWORK_FAILURE" | "HTTP_429" | "HTTP_503";
|
||||
export type BodyDisposition =
|
||||
| "FULLY_READ_WITHIN_BOUND"
|
||||
| "CANCELLED_WITHOUT_READ"
|
||||
| "REJECTED_LIMIT"
|
||||
| "NO_RESPONSE";
|
||||
|
||||
const attemptStatusSchema = z.union([
|
||||
z.number().int().min(100).max(599),
|
||||
z.literal("NETWORK_REJECTION"),
|
||||
z.literal("PENDING_ABORT"),
|
||||
]);
|
||||
|
||||
export const httpScenarioAssertionGroupsSchema = z
|
||||
.object({
|
||||
status: z
|
||||
.object({
|
||||
attempts: z.array(attemptStatusSchema).min(1),
|
||||
final: attemptStatusSchema,
|
||||
})
|
||||
.strict(),
|
||||
outcome: z.object({ kind: z.string().min(1), detail: z.string().nullable() }).strict(),
|
||||
effect: z.object({ outcome: z.string().min(1), observer: z.string().min(1) }).strict(),
|
||||
retry: z
|
||||
.object({
|
||||
count: z.number().int().nonnegative(),
|
||||
reasons: z.array(z.enum(["NETWORK_FAILURE", "HTTP_429", "HTTP_503"])),
|
||||
})
|
||||
.strict(),
|
||||
fetch: z
|
||||
.object({
|
||||
count: z.number().int().positive(),
|
||||
observerAttempts: z.number().int().positive(),
|
||||
agrees: z.boolean(),
|
||||
})
|
||||
.strict(),
|
||||
media: z.object({ attempts: z.array(z.string().nullable()).min(1), final: z.string().nullable() }).strict(),
|
||||
body: z
|
||||
.object({
|
||||
attempts: z
|
||||
.array(
|
||||
z
|
||||
.object({
|
||||
disposition: z.enum([
|
||||
"FULLY_READ_WITHIN_BOUND",
|
||||
"CANCELLED_WITHOUT_READ",
|
||||
"REJECTED_LIMIT",
|
||||
"NO_RESPONSE",
|
||||
]),
|
||||
pulledBytes: z.number().int().nonnegative(),
|
||||
ceiling: z.number().int().nonnegative(),
|
||||
})
|
||||
.strict(),
|
||||
)
|
||||
.min(1),
|
||||
})
|
||||
.strict(),
|
||||
scope: z
|
||||
.object({
|
||||
start: z.literal("CURRENT"),
|
||||
end: z.enum(["CURRENT", "STALE"]),
|
||||
signal: z.enum(["ACTIVE", "ABORTED"]),
|
||||
cancellationOwner: z.enum(["NONE", "CALLER", "SCOPE_FENCE", "DEADLINE"]),
|
||||
})
|
||||
.strict(),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((groups, context) => {
|
||||
const fail = (path: (string | number)[], message: string) => {
|
||||
context.addIssue({ code: "custom", path, message });
|
||||
};
|
||||
if (groups.status.final !== groups.status.attempts.at(-1)) {
|
||||
fail(["status", "final"], "must equal the final attempt status");
|
||||
}
|
||||
if (groups.retry.count !== groups.retry.reasons.length) {
|
||||
fail(["retry", "count"], "must equal retry reasons length");
|
||||
}
|
||||
if (groups.retry.count !== groups.fetch.count - 1) {
|
||||
fail(["retry", "count"], "must equal the non-final fetch attempt count");
|
||||
}
|
||||
for (const [index, reason] of groups.retry.reasons.entries()) {
|
||||
const status = groups.status.attempts[index];
|
||||
const expectedReason =
|
||||
status === "NETWORK_REJECTION"
|
||||
? "NETWORK_FAILURE"
|
||||
: status === 429
|
||||
? "HTTP_429"
|
||||
: status === 503
|
||||
? "HTTP_503"
|
||||
: null;
|
||||
if (reason !== expectedReason) {
|
||||
fail(
|
||||
["retry", "reasons", index],
|
||||
"must match the corresponding non-final attempt status",
|
||||
);
|
||||
}
|
||||
}
|
||||
if (groups.fetch.count !== groups.status.attempts.length) {
|
||||
fail(["fetch", "count"], "must equal status attempts length");
|
||||
}
|
||||
if (groups.fetch.count !== groups.media.attempts.length) {
|
||||
fail(["media", "attempts"], "must equal fetch count");
|
||||
}
|
||||
if (groups.fetch.count !== groups.body.attempts.length) {
|
||||
fail(["body", "attempts"], "must equal fetch count");
|
||||
}
|
||||
if (groups.fetch.observerAttempts !== groups.fetch.count) {
|
||||
fail(["fetch", "observerAttempts"], "must equal physical fetch count");
|
||||
}
|
||||
if (!groups.fetch.agrees) {
|
||||
fail(["fetch", "agrees"], "must prove physical/observer agreement");
|
||||
}
|
||||
if (groups.media.final !== groups.media.attempts.at(-1)) {
|
||||
fail(["media", "final"], "must equal the final attempt media essence");
|
||||
}
|
||||
});
|
||||
|
||||
export type HttpScenarioAssertionGroups = Readonly<{
|
||||
status: Readonly<{ attempts: readonly AttemptStatus[]; final: AttemptStatus }>;
|
||||
outcome: Readonly<{ kind: string; detail: string | null }>;
|
||||
effect: Readonly<{ outcome: string; observer: string }>;
|
||||
retry: Readonly<{ count: number; reasons: readonly RetryReason[] }>;
|
||||
fetch: Readonly<{
|
||||
count: number;
|
||||
observerAttempts: number;
|
||||
agrees: boolean;
|
||||
}>;
|
||||
media: Readonly<{
|
||||
attempts: readonly (string | null)[];
|
||||
final: string | null;
|
||||
}>;
|
||||
body: Readonly<{
|
||||
attempts: readonly Readonly<{
|
||||
disposition: BodyDisposition;
|
||||
pulledBytes: number;
|
||||
ceiling: number;
|
||||
}>[];
|
||||
}>;
|
||||
scope: Readonly<{
|
||||
start: "CURRENT";
|
||||
end: "CURRENT" | "STALE";
|
||||
signal: "ACTIVE" | "ABORTED";
|
||||
cancellationOwner: "NONE" | "CALLER" | "SCOPE_FENCE" | "DEADLINE";
|
||||
}>;
|
||||
}>;
|
||||
|
||||
export const httpScenarioExpectationSchema = z
|
||||
.object({
|
||||
executionId: z.string().min(1),
|
||||
operationId: z.string().min(1),
|
||||
scenarioId: z.string().min(1),
|
||||
expected: httpScenarioAssertionGroupsSchema,
|
||||
testDeadlineOverrideMs: z.number().int().positive().nullable(),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((entry, context) => {
|
||||
if (entry.executionId !== `${entry.operationId}::${entry.scenarioId}`) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["executionId"],
|
||||
message: "must equal operationId::scenarioId",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
export type HttpScenarioExpectation = Readonly<{
|
||||
executionId: string;
|
||||
operationId: string;
|
||||
scenarioId: string;
|
||||
expected: HttpScenarioAssertionGroups;
|
||||
testDeadlineOverrideMs: number | null;
|
||||
}>;
|
||||
|
||||
export const httpScenarioReceiptRowSchema = z
|
||||
.object({
|
||||
executionId: z.string().min(1),
|
||||
expected: httpScenarioAssertionGroupsSchema,
|
||||
observed: httpScenarioAssertionGroupsSchema,
|
||||
testDeadlineOverrideMs: z.number().int().positive().nullable(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export const httpScenarioReceiptSchema = z
|
||||
.object({
|
||||
schemaVersion: z.number().int().positive(),
|
||||
catalogDigest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
|
||||
catalogTotal: z.number().int().nonnegative(),
|
||||
executedIds: z.array(z.string().min(1)),
|
||||
rows: z.array(httpScenarioReceiptRowSchema),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((receipt, context) => {
|
||||
const rowIds = receipt.rows.map((row) => row.executionId);
|
||||
const sortedIds = [...receipt.executedIds].sort((left, right) =>
|
||||
left.localeCompare(right),
|
||||
);
|
||||
const sortedRowIds = [...rowIds].sort((left, right) =>
|
||||
left.localeCompare(right),
|
||||
);
|
||||
if (!sameScenarioJson(receipt.executedIds, sortedIds)) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["executedIds"],
|
||||
message: "must be sorted by execution ID",
|
||||
});
|
||||
}
|
||||
if (!sameScenarioJson(rowIds, sortedRowIds)) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["rows"],
|
||||
message: "must be sorted by execution ID",
|
||||
});
|
||||
}
|
||||
if (!sameScenarioJson(receipt.executedIds, rowIds)) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["rows"],
|
||||
message: "row IDs must exactly equal executed IDs",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
export type HttpScenarioReceipt = Readonly<{
|
||||
schemaVersion: number;
|
||||
catalogDigest: string;
|
||||
catalogTotal: number;
|
||||
executedIds: readonly string[];
|
||||
rows: readonly Readonly<{
|
||||
executionId: string;
|
||||
expected: HttpScenarioAssertionGroups;
|
||||
observed: HttpScenarioAssertionGroups;
|
||||
testDeadlineOverrideMs: number | null;
|
||||
}>[];
|
||||
}>;
|
||||
|
||||
export function stableScenarioJson(value: unknown): string {
|
||||
const normalize = (candidate: unknown): unknown => {
|
||||
if (Array.isArray(candidate)) return candidate.map(normalize);
|
||||
if (candidate && typeof candidate === "object") {
|
||||
return Object.fromEntries(
|
||||
Object.entries(candidate as Readonly<Record<string, unknown>>)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, nested]) => [key, normalize(nested)]),
|
||||
);
|
||||
}
|
||||
return candidate;
|
||||
};
|
||||
return JSON.stringify(normalize(value));
|
||||
}
|
||||
|
||||
export function sameScenarioJson(left: unknown, right: unknown): boolean {
|
||||
return stableScenarioJson(left) === stableScenarioJson(right);
|
||||
}
|
||||
|
||||
export function computeHttpScenarioCatalogDigest(
|
||||
schemaVersion: number,
|
||||
expectations: readonly HttpScenarioExpectation[],
|
||||
): `sha256:${string}` {
|
||||
const tuples = [...expectations]
|
||||
.sort((left, right) => left.executionId.localeCompare(right.executionId))
|
||||
.map((entry) => [
|
||||
entry.executionId,
|
||||
entry.expected.status,
|
||||
entry.expected.outcome,
|
||||
entry.expected.effect,
|
||||
entry.expected.retry,
|
||||
entry.expected.fetch,
|
||||
entry.expected.media,
|
||||
entry.expected.body,
|
||||
entry.expected.scope,
|
||||
entry.testDeadlineOverrideMs,
|
||||
]);
|
||||
return `sha256:${createHash("sha256")
|
||||
.update(stableScenarioJson([schemaVersion, ...tuples]))
|
||||
.digest("hex")}`;
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/**
|
||||
* Compile a checked-in JSON Schema and assert a concrete artifact against it.
|
||||
* Conversion failures are fatal too: an unsupported or malformed schema must
|
||||
* not silently turn a release schema into documentation-only metadata.
|
||||
*/
|
||||
export function assertMatchesJsonSchema(
|
||||
schemaDocument: unknown,
|
||||
value: unknown,
|
||||
label: string,
|
||||
): void {
|
||||
try {
|
||||
const schema = z.fromJSONSchema(schemaDocument as never);
|
||||
const result = schema.safeParse(value);
|
||||
if (!result.success) {
|
||||
throw new TypeError(z.prettifyError(result.error));
|
||||
}
|
||||
} catch (error) {
|
||||
throw new TypeError(`${label} does not satisfy its checked-in JSON Schema.`, {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,206 @@
|
||||
import {
|
||||
dependencyDiffArtifactSchema,
|
||||
dependencyInventoryArtifactSchema,
|
||||
licenseReportArtifactSchema,
|
||||
supplyChainVerificationArtifactSchema,
|
||||
vulnerabilityReportArtifactSchema,
|
||||
} from "../contracts/release-artifacts.ts";
|
||||
import type { DistOutput } from "./release-candidate.ts";
|
||||
import {
|
||||
diffDependencyInventories,
|
||||
supplyChainDigest,
|
||||
validateDependencyReview,
|
||||
validateLicensePolicy,
|
||||
} from "./supply-chain.ts";
|
||||
|
||||
type Document = Record<string, unknown>;
|
||||
|
||||
export const LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS = Object.freeze({
|
||||
promotionStatus: "FAIL_UNVERIFIED" as const,
|
||||
vulnerabilityStatus: "FAIL_UNVERIFIED" as const,
|
||||
provenanceAttestationStatus: "FAIL_UNVERIFIED" as const,
|
||||
});
|
||||
|
||||
export function verifyLocalSupplyChainDefaults(stored: unknown): string[] {
|
||||
const parsed = supplyChainVerificationArtifactSchema.safeParse(stored);
|
||||
if (
|
||||
!parsed.success ||
|
||||
parsed.data.promotionStatus !==
|
||||
LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS.promotionStatus ||
|
||||
parsed.data.vulnerabilityStatus !==
|
||||
LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS.vulnerabilityStatus ||
|
||||
parsed.data.provenanceAttestationStatus !==
|
||||
LOCAL_SUPPLY_CHAIN_UNVERIFIED_DEFAULTS.provenanceAttestationStatus
|
||||
) {
|
||||
return [
|
||||
"supply-chain verification provider defaults are not local FAIL_UNVERIFIED",
|
||||
];
|
||||
}
|
||||
return [];
|
||||
}
|
||||
|
||||
export function createLocalVulnerabilityReport(lockfileSha256: string) {
|
||||
return vulnerabilityReportArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
provider: "UNCONFIGURED",
|
||||
scannedLockfileSha256: lockfileSha256,
|
||||
status: "FAIL_UNVERIFIED",
|
||||
findings: [],
|
||||
exceptionsApplied: [],
|
||||
failures: ["external vulnerability provider report is missing"],
|
||||
blocking: [],
|
||||
});
|
||||
}
|
||||
|
||||
export function compareStoredLocalVulnerabilityReport(
|
||||
lockfileSha256: string,
|
||||
stored: unknown,
|
||||
): string[] {
|
||||
const parsed = vulnerabilityReportArtifactSchema.safeParse(stored);
|
||||
if (
|
||||
!parsed.success ||
|
||||
supplyChainDigest(parsed.data) !==
|
||||
supplyChainDigest(createLocalVulnerabilityReport(lockfileSha256))
|
||||
) {
|
||||
return [
|
||||
"local vulnerability report does not match exact unconfigured defaults",
|
||||
];
|
||||
}
|
||||
return [];
|
||||
}
|
||||
|
||||
export function recomputeDependencyEvidence(input: Readonly<{
|
||||
inventory: unknown;
|
||||
baseline: unknown;
|
||||
baselineApproval: unknown;
|
||||
dependencyChangeEvidence: unknown;
|
||||
skipBaseline?: boolean;
|
||||
}>) {
|
||||
const inventory = dependencyInventoryArtifactSchema.parse(input.inventory);
|
||||
const baseline = asDocument(input.baseline);
|
||||
const approval = asDocument(input.baselineApproval);
|
||||
const dependencyChangeEvidence = asDocument(input.dependencyChangeEvidence);
|
||||
const failures: string[] = [];
|
||||
const skipBaseline = input.skipBaseline === true;
|
||||
let diff: ReturnType<typeof diffDependencyInventories> = Object.freeze({
|
||||
added: Object.freeze([]),
|
||||
removed: Object.freeze([]),
|
||||
changed: Object.freeze([]),
|
||||
upgrades: Object.freeze([]),
|
||||
});
|
||||
let review: ReturnType<typeof validateDependencyReview> = Object.freeze({
|
||||
passed: skipBaseline,
|
||||
highRisk: Object.freeze([]),
|
||||
failures: Object.freeze(
|
||||
skipBaseline ? [] : ["dependency baseline unavailable"],
|
||||
),
|
||||
});
|
||||
const baselineDigest = baseline ? supplyChainDigest(baseline) : null;
|
||||
|
||||
if (baseline && approval) {
|
||||
diff = diffDependencyInventories(baseline, inventory);
|
||||
review = validateDependencyReview(
|
||||
diff,
|
||||
inventory,
|
||||
dependencyChangeEvidence ?? {},
|
||||
);
|
||||
if (
|
||||
approval.schemaVersion !== 1 ||
|
||||
approval.snapshotDigest !== baselineDigest ||
|
||||
typeof approval.owner !== "string" ||
|
||||
approval.owner.trim().length === 0
|
||||
) {
|
||||
failures.push("dependency baseline approval digest mismatch");
|
||||
}
|
||||
} else if (!skipBaseline) {
|
||||
failures.push("dependency baseline and approval are required");
|
||||
}
|
||||
failures.push(...review.failures);
|
||||
|
||||
const report = dependencyDiffArtifactSchema.parse({
|
||||
schemaVersion: 2,
|
||||
baselineDigest,
|
||||
currentDigest: supplyChainDigest(inventory),
|
||||
...diff,
|
||||
highRisk: review.highRisk,
|
||||
reviewFailures: review.failures,
|
||||
});
|
||||
return Object.freeze({
|
||||
report,
|
||||
dependencyDiff: diff,
|
||||
highRisk: review.highRisk,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
|
||||
export function compareStoredDependencyEvidence(
|
||||
recomputed: ReturnType<typeof recomputeDependencyEvidence>,
|
||||
stored: unknown,
|
||||
): string[] {
|
||||
const parsed = dependencyDiffArtifactSchema.safeParse(stored);
|
||||
if (
|
||||
!parsed.success ||
|
||||
supplyChainDigest(parsed.data) !== supplyChainDigest(recomputed.report)
|
||||
) {
|
||||
return ["stored dependency diff does not match recomputed policy evidence"];
|
||||
}
|
||||
return [...recomputed.failures];
|
||||
}
|
||||
|
||||
export function recomputeLicenseEvidence(input: Readonly<{
|
||||
inventory: unknown;
|
||||
policy: unknown;
|
||||
}>) {
|
||||
const inventory = dependencyInventoryArtifactSchema.parse(input.inventory);
|
||||
const policy = asDocument(input.policy) ?? {};
|
||||
const result = validateLicensePolicy(inventory, policy);
|
||||
const report = licenseReportArtifactSchema.parse({
|
||||
schemaVersion: 1,
|
||||
status: result.passed ? "PASS" : "FAIL",
|
||||
dependencyCount: inventory.dependencyCount,
|
||||
results: result.results,
|
||||
failures: result.failures,
|
||||
});
|
||||
return Object.freeze({
|
||||
report,
|
||||
failures: result.failures,
|
||||
});
|
||||
}
|
||||
|
||||
export function compareStoredLicenseEvidence(
|
||||
recomputed: ReturnType<typeof recomputeLicenseEvidence>,
|
||||
stored: unknown,
|
||||
): string[] {
|
||||
const parsed = licenseReportArtifactSchema.safeParse(stored);
|
||||
if (
|
||||
!parsed.success ||
|
||||
supplyChainDigest(parsed.data) !== supplyChainDigest(recomputed.report)
|
||||
) {
|
||||
return ["stored license report does not match recomputed policy evidence"];
|
||||
}
|
||||
return [...recomputed.failures];
|
||||
}
|
||||
|
||||
export function distChecksumsText(outputs: readonly DistOutput[]): string {
|
||||
return `${[...outputs]
|
||||
.sort((left, right) => left.path.localeCompare(right.path))
|
||||
.map((output) => `${output.sha256} ${output.path}`)
|
||||
.join("\n")}\n`;
|
||||
}
|
||||
|
||||
export function verifyStoredDistChecksums(
|
||||
outputs: readonly DistOutput[],
|
||||
stored: string,
|
||||
): string[] {
|
||||
return stored === distChecksumsText(outputs)
|
||||
? []
|
||||
: ["stored dist checksums do not match current outputs"];
|
||||
}
|
||||
|
||||
function asDocument(value: unknown): Document | null {
|
||||
return value !== null &&
|
||||
typeof value === "object" &&
|
||||
!Array.isArray(value)
|
||||
? (value as Document)
|
||||
: null;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,57 @@
|
||||
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
|
||||
|
||||
export const MANUAL_A11Y_ROUTE_IDS = Object.freeze(
|
||||
Object.values(ROUTE_REGISTRY).map((route) => route.routeId),
|
||||
);
|
||||
|
||||
const REVIEW_FIELDS = Object.freeze([
|
||||
"M1 Keyboard",
|
||||
"M2 Visible focus",
|
||||
"M3 Route focus",
|
||||
"M4 Modal focus",
|
||||
"M5 Error association",
|
||||
"M6 Color signal",
|
||||
"M7 Reduced motion",
|
||||
"Screen reader",
|
||||
]);
|
||||
|
||||
export function validateManualA11yEvidence(content: string) {
|
||||
const fields = Object.fromEntries(
|
||||
content
|
||||
.split(/\r?\n/)
|
||||
.map((line) => /^([^:]+):\s*(.*)$/.exec(line))
|
||||
.filter((match): match is RegExpExecArray => match !== null)
|
||||
.map((match) => [
|
||||
match[1].trim(),
|
||||
match[2].trim(),
|
||||
]),
|
||||
);
|
||||
const failures: string[] = [];
|
||||
if (fields.Status !== "reviewed") failures.push("Status");
|
||||
if (!fields["Route ID"]) failures.push("Route ID");
|
||||
if (!fields["Release ID"]) failures.push("Release ID");
|
||||
if (!fields.Reviewer) failures.push("Reviewer");
|
||||
if (!fields.Signature) failures.push("Signature");
|
||||
if (fields.Attestation !== "accepted") failures.push("Attestation");
|
||||
if (
|
||||
!fields["Reviewed at"] ||
|
||||
!Number.isFinite(Date.parse(fields["Reviewed at"]))
|
||||
) {
|
||||
failures.push("Reviewed at");
|
||||
}
|
||||
|
||||
for (const field of REVIEW_FIELDS) {
|
||||
const result = fields[field];
|
||||
if (
|
||||
result !== "pass" &&
|
||||
!/^not-applicable \(.+\)$/.test(result ?? "")
|
||||
) {
|
||||
failures.push(field);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
fields: Object.freeze(fields),
|
||||
failures: Object.freeze(failures),
|
||||
passed: failures.length === 0,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,373 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { lstat, readdir, realpath } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
import { gzipSync } from "node:zlib";
|
||||
|
||||
import {
|
||||
build,
|
||||
normalizePath,
|
||||
type Plugin,
|
||||
version as viteVersion,
|
||||
} from "vite";
|
||||
|
||||
const RECIPE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
||||
const SOURCE_EXTENSION = /\.(?:[cm]?[jt]s|[jt]sx)$/;
|
||||
const DECLARATION_FILE = /\.d\.[cm]?ts$/;
|
||||
|
||||
type EmittedOutput =
|
||||
| Readonly<{
|
||||
type: "chunk";
|
||||
fileName: string;
|
||||
code: string;
|
||||
}>
|
||||
| Readonly<{
|
||||
type: "asset";
|
||||
fileName: string;
|
||||
source: string | Uint8Array;
|
||||
}>;
|
||||
|
||||
export type OptionalRecipeBundleOutput = Readonly<{
|
||||
fileName: string;
|
||||
bytes: number;
|
||||
gzipBytes: number;
|
||||
sha256: string;
|
||||
}>;
|
||||
|
||||
export type OptionalRecipeBundleMeasurement = Readonly<{
|
||||
recipeId: string;
|
||||
sourceRoots: readonly string[];
|
||||
sourceFileCount: number;
|
||||
toolchain: Readonly<{
|
||||
bundler: "vite";
|
||||
viteVersion: string;
|
||||
mode: "production";
|
||||
target: "es2022";
|
||||
format: "es";
|
||||
minifier: "esbuild";
|
||||
treeshake: false;
|
||||
compression: "node-zlib-gzip";
|
||||
}>;
|
||||
outputs: readonly OptionalRecipeBundleOutput[];
|
||||
bytes: number;
|
||||
gzipBytes: number;
|
||||
bundleBudgetGzipBytes: number;
|
||||
remainingGzipBytes: number;
|
||||
sha256: string;
|
||||
passed: boolean;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* Builds an uncomposed reference runtime as a synthetic production consumer.
|
||||
* Every catalog-owned source module is exposed as an entry namespace and
|
||||
* tree-shaking is disabled so internal fail-closed paths remain in the budget.
|
||||
*/
|
||||
export async function measureOptionalRecipeBundle(input: Readonly<{
|
||||
recipeId: string;
|
||||
sourceRoots: readonly string[];
|
||||
bundleBudgetGzipBytes: number;
|
||||
workspaceRoot?: string;
|
||||
}>): Promise<OptionalRecipeBundleMeasurement> {
|
||||
const recipeId = validateRecipeId(input.recipeId);
|
||||
const bundleBudgetGzipBytes = positiveSafeInteger(
|
||||
input.bundleBudgetGzipBytes,
|
||||
"Optional recipe bundle budget",
|
||||
);
|
||||
const workspaceRoot = await realpath(
|
||||
path.resolve(input.workspaceRoot ?? process.cwd()),
|
||||
);
|
||||
const sourceRoots = validateSourceRoots(input.sourceRoots);
|
||||
const sourceFiles = await resolveSourceFiles(
|
||||
workspaceRoot,
|
||||
sourceRoots,
|
||||
);
|
||||
const virtualEntry =
|
||||
`virtual:optional-reference-runtime-entry/${recipeId}`;
|
||||
const resolvedVirtualEntry = `\0${virtualEntry}`;
|
||||
const entrySource = sourceFiles
|
||||
.map(
|
||||
(sourceFile, index) =>
|
||||
`export * as source${index} from ${JSON.stringify(
|
||||
viteSourceSpecifier(sourceFile),
|
||||
)};`,
|
||||
)
|
||||
.join("\n")
|
||||
.concat("\n");
|
||||
const preservePublicEntryPlugin = {
|
||||
name: "optional-reference-runtime-entry",
|
||||
enforce: "pre",
|
||||
resolveId(id) {
|
||||
return id === virtualEntry ? resolvedVirtualEntry : null;
|
||||
},
|
||||
load(id) {
|
||||
return id === resolvedVirtualEntry ? entrySource : null;
|
||||
},
|
||||
options(options) {
|
||||
return {
|
||||
...options,
|
||||
preserveEntrySignatures: "strict",
|
||||
};
|
||||
},
|
||||
} satisfies Plugin;
|
||||
const buildResult = await build({
|
||||
root: workspaceRoot,
|
||||
configFile: false,
|
||||
envFile: false,
|
||||
mode: "production",
|
||||
publicDir: false,
|
||||
clearScreen: false,
|
||||
logLevel: "silent",
|
||||
plugins: [preservePublicEntryPlugin],
|
||||
build: {
|
||||
target: "es2022",
|
||||
minify: "esbuild",
|
||||
sourcemap: false,
|
||||
write: false,
|
||||
emptyOutDir: false,
|
||||
copyPublicDir: false,
|
||||
cssCodeSplit: false,
|
||||
reportCompressedSize: false,
|
||||
rollupOptions: {
|
||||
input: virtualEntry,
|
||||
// Budget the complete selected runtime, including internal fail-closed
|
||||
// guards that a synthetic consumer cannot predict it will exercise.
|
||||
treeshake: false,
|
||||
output: {
|
||||
format: "es",
|
||||
entryFileNames: `${recipeId}.js`,
|
||||
chunkFileNames: `${recipeId}-chunk-[hash].js`,
|
||||
assetFileNames: `${recipeId}-asset-[name]-[hash][extname]`,
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
const emitted = emittedOutputs(buildResult);
|
||||
if (emitted.length === 0) {
|
||||
throw new TypeError("Optional recipe bundle emitted no output.");
|
||||
}
|
||||
const outputs = emitted
|
||||
.map((output) => {
|
||||
const bytes = outputBytes(output);
|
||||
return Object.freeze({
|
||||
fileName: output.fileName,
|
||||
bytes: bytes.byteLength,
|
||||
gzipBytes: gzipSync(bytes).byteLength,
|
||||
sha256: createHash("sha256").update(bytes).digest("hex"),
|
||||
});
|
||||
})
|
||||
.sort((left, right) => compareText(left.fileName, right.fileName));
|
||||
const aggregateHash = createHash("sha256");
|
||||
for (const output of outputs) {
|
||||
aggregateHash.update(output.fileName);
|
||||
aggregateHash.update("\0");
|
||||
aggregateHash.update(output.sha256);
|
||||
aggregateHash.update("\0");
|
||||
}
|
||||
const bytes = outputs.reduce(
|
||||
(total, output) => total + output.bytes,
|
||||
0,
|
||||
);
|
||||
const gzipBytes = outputs.reduce(
|
||||
(total, output) => total + output.gzipBytes,
|
||||
0,
|
||||
);
|
||||
|
||||
return Object.freeze({
|
||||
recipeId,
|
||||
sourceRoots: Object.freeze([...sourceRoots]),
|
||||
sourceFileCount: sourceFiles.length,
|
||||
toolchain: Object.freeze({
|
||||
bundler: "vite" as const,
|
||||
viteVersion,
|
||||
mode: "production" as const,
|
||||
target: "es2022" as const,
|
||||
format: "es" as const,
|
||||
minifier: "esbuild" as const,
|
||||
treeshake: false as const,
|
||||
compression: "node-zlib-gzip" as const,
|
||||
}),
|
||||
outputs: Object.freeze(outputs),
|
||||
bytes,
|
||||
gzipBytes,
|
||||
bundleBudgetGzipBytes,
|
||||
remainingGzipBytes: bundleBudgetGzipBytes - gzipBytes,
|
||||
sha256: aggregateHash.digest("hex"),
|
||||
passed: gzipBytes <= bundleBudgetGzipBytes,
|
||||
});
|
||||
}
|
||||
|
||||
async function resolveSourceFiles(
|
||||
workspaceRoot: string,
|
||||
sourceRoots: readonly string[],
|
||||
): Promise<readonly string[]> {
|
||||
const sourceBoundary = await realpath(path.join(workspaceRoot, "src"));
|
||||
const discovered: string[] = [];
|
||||
for (const sourceRoot of sourceRoots) {
|
||||
const target = path.resolve(workspaceRoot, sourceRoot);
|
||||
assertInsideSourceBoundary(target, sourceBoundary);
|
||||
const rootMetadata = await lstat(target);
|
||||
if (rootMetadata.isSymbolicLink()) {
|
||||
throw new TypeError("Optional recipe source root cannot be a symlink.");
|
||||
}
|
||||
assertInsideSourceBoundary(await realpath(target), sourceBoundary);
|
||||
if (
|
||||
rootMetadata.isFile() &&
|
||||
(!SOURCE_EXTENSION.test(target) || DECLARATION_FILE.test(target))
|
||||
) {
|
||||
throw new TypeError("Optional recipe source root is not executable source.");
|
||||
}
|
||||
discovered.push(
|
||||
...(await collectExecutableSources(target, sourceBoundary)),
|
||||
);
|
||||
}
|
||||
const unique = [...new Set(discovered)].sort((left, right) =>
|
||||
compareText(
|
||||
normalizePath(path.relative(workspaceRoot, left)),
|
||||
normalizePath(path.relative(workspaceRoot, right)),
|
||||
),
|
||||
);
|
||||
if (unique.length === 0) {
|
||||
throw new TypeError("Optional recipe source roots contain no executable source.");
|
||||
}
|
||||
return Object.freeze(unique);
|
||||
}
|
||||
|
||||
async function collectExecutableSources(
|
||||
target: string,
|
||||
sourceBoundary: string,
|
||||
): Promise<string[]> {
|
||||
const metadata = await lstat(target);
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError("Optional recipe source cannot be a symlink.");
|
||||
}
|
||||
assertInsideSourceBoundary(target, sourceBoundary);
|
||||
if (metadata.isFile()) {
|
||||
return SOURCE_EXTENSION.test(target) && !DECLARATION_FILE.test(target)
|
||||
? [target]
|
||||
: [];
|
||||
}
|
||||
if (!metadata.isDirectory()) return [];
|
||||
const entries = (await readdir(target, { withFileTypes: true })).sort(
|
||||
(left, right) => compareText(left.name, right.name),
|
||||
);
|
||||
const groups = await Promise.all(
|
||||
entries.map((entry) =>
|
||||
collectExecutableSources(
|
||||
path.join(target, entry.name),
|
||||
sourceBoundary,
|
||||
),
|
||||
),
|
||||
);
|
||||
return groups.flat();
|
||||
}
|
||||
|
||||
function emittedOutputs(value: unknown): readonly EmittedOutput[] {
|
||||
const buildOutputs = Array.isArray(value) ? value : [value];
|
||||
const emitted: EmittedOutput[] = [];
|
||||
for (const buildOutput of buildOutputs) {
|
||||
if (!isRecord(buildOutput) || !Array.isArray(buildOutput.output)) {
|
||||
throw new TypeError("Optional recipe bundle output is invalid.");
|
||||
}
|
||||
for (const output of buildOutput.output) {
|
||||
if (!isRecord(output)) {
|
||||
throw new TypeError("Optional recipe emitted output is invalid.");
|
||||
}
|
||||
if (
|
||||
output.type === "chunk" &&
|
||||
typeof output.fileName === "string" &&
|
||||
typeof output.code === "string"
|
||||
) {
|
||||
emitted.push({
|
||||
type: "chunk",
|
||||
fileName: output.fileName,
|
||||
code: output.code,
|
||||
});
|
||||
} else if (
|
||||
output.type === "asset" &&
|
||||
typeof output.fileName === "string" &&
|
||||
(typeof output.source === "string" ||
|
||||
output.source instanceof Uint8Array)
|
||||
) {
|
||||
emitted.push({
|
||||
type: "asset",
|
||||
fileName: output.fileName,
|
||||
source: output.source,
|
||||
});
|
||||
} else {
|
||||
throw new TypeError("Optional recipe emitted output shape is invalid.");
|
||||
}
|
||||
}
|
||||
}
|
||||
return emitted;
|
||||
}
|
||||
|
||||
function outputBytes(output: EmittedOutput): Buffer {
|
||||
if (output.type === "chunk") {
|
||||
return Buffer.from(output.code, "utf8");
|
||||
}
|
||||
return Buffer.from(output.source);
|
||||
}
|
||||
|
||||
function validateRecipeId(value: unknown): string {
|
||||
if (typeof value !== "string" || !RECIPE_ID.test(value)) {
|
||||
throw new TypeError("Optional recipe ID is invalid.");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function validateSourceRoots(value: unknown): readonly string[] {
|
||||
if (
|
||||
!Array.isArray(value) ||
|
||||
value.length === 0 ||
|
||||
value.length > 32 ||
|
||||
value.some(
|
||||
(sourceRoot) =>
|
||||
typeof sourceRoot !== "string" ||
|
||||
!sourceRoot.startsWith("src/") ||
|
||||
sourceRoot.includes("\\") ||
|
||||
sourceRoot
|
||||
.split("/")
|
||||
.some(
|
||||
(segment) =>
|
||||
segment.length === 0 || segment === "." || segment === "..",
|
||||
),
|
||||
) ||
|
||||
new Set(value).size !== value.length
|
||||
) {
|
||||
throw new TypeError("Optional recipe source roots are invalid.");
|
||||
}
|
||||
return Object.freeze([...value].sort(compareText));
|
||||
}
|
||||
|
||||
function assertInsideSourceBoundary(
|
||||
target: string,
|
||||
sourceBoundary: string,
|
||||
): void {
|
||||
const relative = path.relative(sourceBoundary, target);
|
||||
if (
|
||||
relative === ".." ||
|
||||
relative.startsWith(`..${path.sep}`) ||
|
||||
path.isAbsolute(relative)
|
||||
) {
|
||||
throw new TypeError("Optional recipe source escaped the source boundary.");
|
||||
}
|
||||
}
|
||||
|
||||
function viteSourceSpecifier(sourceFile: string): string {
|
||||
return pathToFileURL(sourceFile).href;
|
||||
}
|
||||
|
||||
function positiveSafeInteger(value: unknown, name: string): number {
|
||||
if (!Number.isSafeInteger(value) || (value as number) < 1) {
|
||||
throw new TypeError(`${name} is invalid.`);
|
||||
}
|
||||
return value as number;
|
||||
}
|
||||
|
||||
function compareText(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
@@ -0,0 +1,441 @@
|
||||
import { readFile, readdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
export const REQUIRED_RECIPE_IDS = Object.freeze([
|
||||
"analytics-error-sink",
|
||||
"browser-permission",
|
||||
"client-workflow",
|
||||
"feature-flag",
|
||||
"file-transfer",
|
||||
"generated-api",
|
||||
"large-data-ui",
|
||||
"multi-tab",
|
||||
"offline-indexeddb",
|
||||
"realtime",
|
||||
"service-worker-pwa",
|
||||
"web-worker",
|
||||
] as const);
|
||||
|
||||
const lifecycleRecipes: ReadonlySet<string> = new Set([
|
||||
"analytics-error-sink",
|
||||
"browser-permission",
|
||||
"client-workflow",
|
||||
"file-transfer",
|
||||
"generated-api",
|
||||
"multi-tab",
|
||||
"offline-indexeddb",
|
||||
"realtime",
|
||||
"service-worker-pwa",
|
||||
"web-worker",
|
||||
]);
|
||||
|
||||
type Document = Readonly<Record<string, unknown>>;
|
||||
export type OptionalRecipeSourceViolation = Readonly<{
|
||||
ruleId: string;
|
||||
path: string;
|
||||
}>;
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function recordValue(value: unknown): Record<string, unknown> {
|
||||
return isRecord(value) ? value : {};
|
||||
}
|
||||
|
||||
function recordRows(value: unknown): Record<string, unknown>[] {
|
||||
return Array.isArray(value) ? value.filter(isRecord) : [];
|
||||
}
|
||||
|
||||
function nonEmptyStrings(value: unknown): value is string[] {
|
||||
return (
|
||||
Array.isArray(value) &&
|
||||
value.length > 0 &&
|
||||
value.every(
|
||||
(entry): entry is string =>
|
||||
typeof entry === "string" && entry.trim().length > 0,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function packageVersions(value: unknown): Record<string, string> {
|
||||
return Object.fromEntries(
|
||||
Object.entries(recordValue(value)).filter(
|
||||
(entry): entry is [string, string] => typeof entry[1] === "string",
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
export function validateRecipeCatalog(
|
||||
input: unknown,
|
||||
packageDocument: Document,
|
||||
): string[] {
|
||||
const document = recordValue(input);
|
||||
const violations: string[] = [];
|
||||
if (document.schemaVersion !== 1) violations.push("CATALOG_SCHEMA_VERSION");
|
||||
if (document.decisionId !== "VD-10") violations.push("CATALOG_DECISION");
|
||||
if (document.defaultStatus !== "NOT_INSTALLED") {
|
||||
violations.push("CATALOG_DEFAULT_MUST_BE_NOT_INSTALLED");
|
||||
}
|
||||
if (
|
||||
!Array.isArray(document.productionRuntimeDependencies) ||
|
||||
document.productionRuntimeDependencies.length > 0
|
||||
) {
|
||||
violations.push("UNSELECTED_RUNTIME_DEPENDENCY");
|
||||
}
|
||||
if (!nonEmptyStrings(document.vendorPackagePatterns)) {
|
||||
violations.push("VENDOR_PATTERN_CATALOG");
|
||||
}
|
||||
if (!Array.isArray(document.recipes)) {
|
||||
return [...violations, "RECIPE_CATALOG_MISSING"];
|
||||
}
|
||||
|
||||
const recipes = recordRows(document.recipes);
|
||||
const actualIds = recipes.map((recipe) => String(recipe.id ?? "")).sort();
|
||||
if (JSON.stringify(actualIds) !== JSON.stringify(REQUIRED_RECIPE_IDS)) {
|
||||
violations.push("RECIPE_ID_SET");
|
||||
}
|
||||
if (new Set(actualIds).size !== actualIds.length) {
|
||||
violations.push("RECIPE_ID_DUPLICATE");
|
||||
}
|
||||
|
||||
for (const recipe of recipes) {
|
||||
const id = typeof recipe.id === "string" ? recipe.id : "unknown";
|
||||
if (recipe.status !== "RECIPE_AVAILABLE") {
|
||||
violations.push(`${id}:STATUS_MUST_NOT_CLAIM_INSTALLED`);
|
||||
}
|
||||
for (const field of [
|
||||
"trigger",
|
||||
"boundary",
|
||||
"port",
|
||||
"fake",
|
||||
"owner",
|
||||
"fallback",
|
||||
"serverStatePolicy",
|
||||
] as const) {
|
||||
const value = recipe[field];
|
||||
if (typeof value !== "string" || value.trim().length === 0) {
|
||||
violations.push(`${id}:MISSING_${field.toUpperCase()}`);
|
||||
}
|
||||
}
|
||||
for (const field of [
|
||||
"forbiddenWhen",
|
||||
"failureKinds",
|
||||
"securityPrivacy",
|
||||
"removal",
|
||||
] as const) {
|
||||
if (!nonEmptyStrings(recipe[field])) {
|
||||
violations.push(`${id}:MISSING_${field.toUpperCase()}`);
|
||||
}
|
||||
}
|
||||
if (
|
||||
typeof recipe.bundleBudgetGzipBytes !== "number" ||
|
||||
!Number.isInteger(recipe.bundleBudgetGzipBytes) ||
|
||||
recipe.bundleBudgetGzipBytes < 1
|
||||
) {
|
||||
violations.push(`${id}:INVALID_BUNDLE_BUDGET`);
|
||||
}
|
||||
if (recipe.owner === "frontend-platform") {
|
||||
violations.push(`${id}:PROJECT_OWNER_NOT_ASSIGNED`);
|
||||
}
|
||||
if (lifecycleRecipes.has(id) && !nonEmptyStrings(recipe.lifecycleMethods)) {
|
||||
violations.push(`${id}:CLEANUP_CONTRACT_MISSING`);
|
||||
}
|
||||
if (
|
||||
id === "client-workflow" &&
|
||||
recipe.serverStatePolicy !== "reference-only"
|
||||
) {
|
||||
violations.push(`${id}:SERVER_STATE_DUPLICATION_POLICY`);
|
||||
}
|
||||
}
|
||||
|
||||
const dependencies = {
|
||||
...packageVersions(packageDocument.dependencies),
|
||||
...packageVersions(packageDocument.devDependencies),
|
||||
};
|
||||
const packageScripts = packageVersions(packageDocument.scripts);
|
||||
for (const recipe of recipes) {
|
||||
if (recipe.referenceRuntime === undefined) continue;
|
||||
const runtime = recordValue(recipe.referenceRuntime);
|
||||
const id = typeof recipe.id === "string" ? recipe.id : "unknown";
|
||||
if (
|
||||
runtime.status !== "AVAILABLE_NOT_COMPOSED" ||
|
||||
runtime.productionComposition !== false
|
||||
) {
|
||||
violations.push(`${id}:REFERENCE_RUNTIME_COMPOSITION`);
|
||||
}
|
||||
if (!nonEmptyStrings(runtime.sourceRoots)) {
|
||||
violations.push(`${id}:REFERENCE_RUNTIME_SOURCE_ROOTS`);
|
||||
} else if (
|
||||
runtime.sourceRoots.some(
|
||||
(sourceRoot) =>
|
||||
!sourceRoot.startsWith("src/") ||
|
||||
sourceRoot.includes("\\") ||
|
||||
sourceRoot.split("/").includes(".."),
|
||||
)
|
||||
) {
|
||||
violations.push(`${id}:REFERENCE_RUNTIME_SOURCE_BOUNDARY`);
|
||||
}
|
||||
if (!nonEmptyStrings(runtime.coveredCapabilities)) {
|
||||
violations.push(`${id}:REFERENCE_RUNTIME_CAPABILITIES`);
|
||||
}
|
||||
if (!nonEmptyStrings(runtime.conformanceScripts)) {
|
||||
violations.push(`${id}:REFERENCE_RUNTIME_CONFORMANCE`);
|
||||
} else {
|
||||
for (const script of runtime.conformanceScripts) {
|
||||
if (!(script in packageScripts)) {
|
||||
violations.push(`${id}:UNKNOWN_CONFORMANCE_SCRIPT:${script}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
const vendorPatterns = Array.isArray(document.vendorPackagePatterns)
|
||||
? document.vendorPackagePatterns.filter(
|
||||
(entry): entry is string => typeof entry === "string",
|
||||
)
|
||||
: [];
|
||||
for (const pattern of vendorPatterns) {
|
||||
const wildcard = pattern.endsWith("*");
|
||||
const prefix = pattern.replace(/\/?\*$/, "");
|
||||
if (
|
||||
Object.keys(dependencies).some(
|
||||
(dependency) =>
|
||||
dependency === prefix ||
|
||||
dependency.startsWith(`${prefix}/`) ||
|
||||
(wildcard && dependency.startsWith(prefix)),
|
||||
)
|
||||
) {
|
||||
violations.push(`UNSELECTED_VENDOR_INSTALLED:${prefix}`);
|
||||
}
|
||||
}
|
||||
return violations;
|
||||
}
|
||||
|
||||
export async function sourceFiles(directory: string): Promise<string[]> {
|
||||
let entries;
|
||||
try {
|
||||
entries = await readdir(directory, { withFileTypes: true });
|
||||
} catch (error: unknown) {
|
||||
if (
|
||||
isRecord(error) &&
|
||||
"code" in error &&
|
||||
error.code === "ENOENT"
|
||||
) {
|
||||
return [];
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
const groups: string[][] = await Promise.all(
|
||||
entries.map((entry) => {
|
||||
const target = path.join(directory, entry.name);
|
||||
return entry.isDirectory()
|
||||
? sourceFiles(target)
|
||||
: /\.(?:[cm]?[jt]s|[jt]sx)$/.test(entry.name)
|
||||
? [target]
|
||||
: [];
|
||||
}),
|
||||
);
|
||||
return groups.flat();
|
||||
}
|
||||
|
||||
export async function scanOptionalRecipeSources(
|
||||
root: string,
|
||||
{ scanProductionBoundary = true }: Readonly<{
|
||||
scanProductionBoundary?: boolean;
|
||||
}> = {},
|
||||
): Promise<OptionalRecipeSourceViolation[]> {
|
||||
const violations: OptionalRecipeSourceViolation[] = [];
|
||||
for (const file of await sourceFiles(root)) {
|
||||
const relative = path.relative(process.cwd(), file).replaceAll("\\", "/");
|
||||
const relativeToRoot = path.relative(root, file).replaceAll("\\", "/");
|
||||
const content = await readFile(file, "utf8");
|
||||
const imports = [
|
||||
...content.matchAll(/(?:from\s*|import\s*\(\s*)["']([^"']+)["']/g),
|
||||
]
|
||||
.map((match) => match[1])
|
||||
.filter((specifier): specifier is string => specifier !== undefined);
|
||||
|
||||
if (
|
||||
scanProductionBoundary &&
|
||||
(relativeToRoot.startsWith("src/") ||
|
||||
(path.basename(path.resolve(root)) === "src" &&
|
||||
!relativeToRoot.startsWith(".."))) &&
|
||||
imports.some((specifier) =>
|
||||
/(?:^|\/)recipes\/frontend-capabilities(?:\/|$)/.test(specifier),
|
||||
)
|
||||
) {
|
||||
violations.push({ ruleId: "PRODUCTION_IMPORTS_RECIPE", path: relative });
|
||||
}
|
||||
|
||||
const productionRelative =
|
||||
path.basename(path.resolve(root)) === "src"
|
||||
? `src/${relativeToRoot}`
|
||||
: relativeToRoot;
|
||||
const isCompositionSource =
|
||||
/(?:^|\/)src\/bootstrap\//.test(productionRelative) ||
|
||||
/(?:^|\/)src\/features\/installed-feature-(?:adapters|runtimes)\./.test(
|
||||
productionRelative,
|
||||
);
|
||||
if (
|
||||
scanProductionBoundary &&
|
||||
isCompositionSource &&
|
||||
(imports.some((specifier) =>
|
||||
/(?:^|\/)adapters\/(?:browser-file-storage|browser-files|browser-transfer|cache-storage|storage\/(?:indexeddb|opfs))(?:\/|$)/.test(
|
||||
specifier,
|
||||
),
|
||||
) ||
|
||||
/["'][^"'\r\n]*(?:^|\/)adapters\/(?:browser-file-storage|browser-files|browser-transfer|cache-storage|storage\/(?:indexeddb|opfs))(?:\/|["'])/u.test(
|
||||
content,
|
||||
))
|
||||
) {
|
||||
violations.push({
|
||||
ruleId: "REFERENCE_RUNTIME_COMPOSED_WITHOUT_SELECTION",
|
||||
path: relative,
|
||||
});
|
||||
}
|
||||
|
||||
const localVendorAdapter =
|
||||
relative.includes("recipes/") && relative.includes("/adapters/");
|
||||
if (
|
||||
!localVendorAdapter &&
|
||||
imports.some((specifier) =>
|
||||
/^(?:@launchdarkly\/|@sentry\/|@opentelemetry\/|@openapitools\/openapi-generator-cli$|@reduxjs\/toolkit$|@tanstack\/react-virtual$|@uppy\/|firebase(?:\/|$)|idb$|react-window$|redux(?:\/|$)|socket\.io-client$|tus-js-client$|workbox-window$|xstate$|zustand$)/.test(
|
||||
specifier,
|
||||
),
|
||||
)
|
||||
) {
|
||||
violations.push({ ruleId: "VENDOR_IMPORT_OUTSIDE_ADAPTER", path: relative });
|
||||
}
|
||||
|
||||
if (
|
||||
/localStorage\s*\.\s*(?:setItem|getItem)\s*\([^)]*(?:credential|password|secret|token)/is.test(
|
||||
content,
|
||||
) ||
|
||||
/searchParams\s*\.\s*set\s*\(\s*["'](?:credential|password|secret|token)/is.test(
|
||||
content,
|
||||
) ||
|
||||
/(?:record|track|emit)\s*\(\s*\{[\s\S]{0,400}(?:credential|password|secret|token)\s*:/i.test(
|
||||
content,
|
||||
)
|
||||
) {
|
||||
violations.push({ ruleId: "CREDENTIAL_LEAK_PATH", path: relative });
|
||||
}
|
||||
|
||||
if (
|
||||
/(?:createStore|configureStore|create\s*\()\s*\([\s\S]{0,600}(?:apiResponse|queryData|serverState)\s*:/i.test(
|
||||
content,
|
||||
)
|
||||
) {
|
||||
violations.push({
|
||||
ruleId: "CLIENT_STORE_DUPLICATES_SERVER_STATE",
|
||||
path: relative,
|
||||
});
|
||||
}
|
||||
}
|
||||
return violations;
|
||||
}
|
||||
|
||||
export async function scanProductionBundle(
|
||||
distRoot: string,
|
||||
): Promise<string[]> {
|
||||
const violations: string[] = [];
|
||||
const forbiddenRuntimeMarkers = [
|
||||
"frontend-optional-recipe-must-not-reach-production",
|
||||
"Browser file runtime hard limits are invalid.",
|
||||
"Object URL allocation failed",
|
||||
"Storage pressure policy is invalid.",
|
||||
"IndexedDB runtime configuration is invalid.",
|
||||
"Invalid IndexedDB schema migration.",
|
||||
"OPFS runtime policy is invalid.",
|
||||
"OPFS operation failed.",
|
||||
"Public Cache Storage policy is invalid.",
|
||||
"Public cache validation failed.",
|
||||
"Presigned capability vault limit is invalid.",
|
||||
"Resumable upload policy is invalid.",
|
||||
"Image CDN policy registry is invalid.",
|
||||
] as const;
|
||||
for (const file of await sourceFiles(distRoot)) {
|
||||
const content = await readFile(file, "utf8");
|
||||
if (forbiddenRuntimeMarkers.some((marker) => content.includes(marker))) {
|
||||
violations.push(path.relative(process.cwd(), file));
|
||||
}
|
||||
}
|
||||
|
||||
const viteManifestPath = path.join(distRoot, ".vite/manifest.json");
|
||||
const emittedModuleInventoryPath = path.join(
|
||||
distRoot,
|
||||
".vite/module-inventory.json",
|
||||
);
|
||||
const moduleInventoryCandidates = [
|
||||
emittedModuleInventoryPath,
|
||||
...(path.resolve(distRoot) === path.resolve("dist")
|
||||
? ["artifacts/quality/vite-module-inventory.json"]
|
||||
: []),
|
||||
];
|
||||
const viteManifestExists = await readFile(viteManifestPath, "utf8")
|
||||
.then(() => true)
|
||||
.catch((error: unknown) => {
|
||||
if (isRecord(error) && error.code === "ENOENT") return false;
|
||||
throw error;
|
||||
});
|
||||
if (!viteManifestExists) return [...new Set(violations)];
|
||||
|
||||
let inventory: unknown;
|
||||
let moduleInventoryPath = emittedModuleInventoryPath;
|
||||
for (const candidate of moduleInventoryCandidates) {
|
||||
try {
|
||||
inventory = JSON.parse(await readFile(candidate, "utf8"));
|
||||
moduleInventoryPath = candidate;
|
||||
break;
|
||||
} catch {
|
||||
// A generated build may move the inventory out of the deploy directory.
|
||||
}
|
||||
}
|
||||
if (inventory === undefined) {
|
||||
violations.push(
|
||||
path.relative(process.cwd(), moduleInventoryPath),
|
||||
);
|
||||
return [...new Set(violations)];
|
||||
}
|
||||
const inventoryDocument = recordValue(inventory);
|
||||
const chunks = recordRows(inventoryDocument.chunks);
|
||||
if (
|
||||
inventoryDocument.schemaVersion !== 1 ||
|
||||
!Array.isArray(inventoryDocument.chunks) ||
|
||||
chunks.length !== inventoryDocument.chunks.length
|
||||
) {
|
||||
violations.push(path.relative(process.cwd(), moduleInventoryPath));
|
||||
return [...new Set(violations)];
|
||||
}
|
||||
|
||||
const forbiddenSourcePrefixes = [
|
||||
"src/application/ports/browser-file-storage/",
|
||||
"src/application/ports/browser-transfer/",
|
||||
"src/adapters/browser-file-storage/",
|
||||
"src/adapters/browser-files/",
|
||||
"src/adapters/browser-transfer/",
|
||||
"src/adapters/cache-storage/",
|
||||
"src/adapters/storage/indexeddb/",
|
||||
"src/adapters/storage/opfs/",
|
||||
] as const;
|
||||
for (const chunk of chunks) {
|
||||
if (
|
||||
typeof chunk.fileName !== "string" ||
|
||||
!Array.isArray(chunk.modules) ||
|
||||
chunk.modules.some((moduleId) => typeof moduleId !== "string")
|
||||
) {
|
||||
violations.push(path.relative(process.cwd(), moduleInventoryPath));
|
||||
continue;
|
||||
}
|
||||
for (const moduleId of chunk.modules as string[]) {
|
||||
if (
|
||||
forbiddenSourcePrefixes.some((prefix) =>
|
||||
moduleId.startsWith(prefix),
|
||||
)
|
||||
) {
|
||||
violations.push(`${chunk.fileName}:${moduleId}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return [...new Set(violations)];
|
||||
}
|
||||
@@ -0,0 +1,994 @@
|
||||
type PackageManager = "pnpm" | "npm" | "yarn";
|
||||
|
||||
type ManagerParseResult = Readonly<{
|
||||
dependencies: readonly string[];
|
||||
unsafeLifecycle: boolean;
|
||||
unsupportedManagerSyntax: boolean;
|
||||
}>;
|
||||
|
||||
type SuppressionState = {
|
||||
effective: boolean | undefined;
|
||||
contradictory: boolean;
|
||||
malformed: boolean;
|
||||
};
|
||||
|
||||
type ShellNpmScopeEnvironmentState = {
|
||||
autoExport: boolean;
|
||||
forbidden: boolean;
|
||||
uncertain: boolean;
|
||||
};
|
||||
|
||||
type ShellCommandPrefix = Readonly<{
|
||||
assignments: readonly Readonly<{
|
||||
dynamicName: boolean;
|
||||
name: string | null;
|
||||
}>[];
|
||||
commandIndex: number;
|
||||
uncertain: boolean;
|
||||
}>;
|
||||
|
||||
type EnvironmentCommandPrefix = Readonly<{
|
||||
assignmentNames: readonly string[];
|
||||
uncertain: boolean;
|
||||
}>;
|
||||
|
||||
type TokenizedShellSegment = Readonly<{
|
||||
tokens: readonly string[];
|
||||
expansionTokens: readonly boolean[];
|
||||
}>;
|
||||
|
||||
const managerNames = new Set<PackageManager>(["pnpm", "npm", "yarn"]);
|
||||
const managerOptionsWithValue = new Set([
|
||||
"-C", "--cache", "--cache-folder", "--config-dir", "--cwd", "--dir", "--filter",
|
||||
"--global-dir", "--globalconfig", "--home", "--lockfile-dir", "--mutex", "--prefix",
|
||||
"--registry", "--store-dir", "--userconfig", "--workspace", "--workspace-dir",
|
||||
]);
|
||||
const managerBooleanOptions = new Set([
|
||||
"--color", "--global", "--no-color", "--offline", "--prefer-offline", "--silent",
|
||||
"--use-stderr", "--verbose", "-g", "-s",
|
||||
]);
|
||||
const npmScriptDispatchBooleanOptions = new Set([
|
||||
"--foreground-scripts", "--if-present", "--ignore-scripts",
|
||||
]);
|
||||
const npmScriptDispatchScopeOptions = new Set([
|
||||
"--prefix", "--workspace", "--workspaces",
|
||||
]);
|
||||
const npmDispatchScopeEnvironmentNames = new Set([
|
||||
"npm_config_globalconfig", "npm_config_prefix", "npm_config_userconfig",
|
||||
"npm_config_workspace", "npm_config_workspaces",
|
||||
]);
|
||||
const npmIndirectConfigAuthorityOptions = new Set([
|
||||
"--globalconfig", "--userconfig",
|
||||
]);
|
||||
const manifestScopeOptions: Readonly<Record<PackageManager, ReadonlySet<string>>> = {
|
||||
pnpm: new Set(["-C", "--dir", "--filter", "--workspace-dir"]),
|
||||
npm: new Set(["--prefix", "--workspace"]),
|
||||
yarn: new Set(["--cwd"]),
|
||||
};
|
||||
const lifecycleMutationCommands = new Set([
|
||||
"add", "ci", "dedupe", "i", "install", "link", "pack", "prune", "publish",
|
||||
"rebuild", "remove", "rm", "uninstall", "unlink", "up", "update", "upgrade",
|
||||
]);
|
||||
const managerBuiltinAliases: Readonly<
|
||||
Record<PackageManager, ReadonlyMap<string, string>>
|
||||
> = {
|
||||
pnpm: new Map([["ln", "link"]]),
|
||||
npm: new Map(),
|
||||
yarn: new Map(),
|
||||
};
|
||||
const unsupportedBuiltinDispatchers: Readonly<
|
||||
Record<PackageManager, ReadonlySet<string>>
|
||||
> = {
|
||||
pnpm: new Set(["dlx", "exec"]),
|
||||
npm: new Set(["exec"]),
|
||||
yarn: new Set(["dlx", "exec", "workspace", "workspaces"]),
|
||||
};
|
||||
const lifecycleBooleanOptions: Readonly<
|
||||
Record<PackageManager, ReadonlySet<string>>
|
||||
> = {
|
||||
pnpm: new Set([
|
||||
"--dry-run", "--force", "--frozen-lockfile", "--lockfile-only",
|
||||
"--no-optional", "--prefer-frozen-lockfile", "--recursive",
|
||||
"--workspace-root", "-D", "-P", "-r", "-w",
|
||||
]),
|
||||
npm: new Set([
|
||||
"--audit", "--dry-run", "--force", "--foreground-scripts", "--fund",
|
||||
"--package-lock-only",
|
||||
]),
|
||||
yarn: new Set([
|
||||
"--check-cache", "--frozen-lockfile", "--ignore-engines",
|
||||
"--ignore-optional", "--immutable", "--immutable-cache", "--inline-builds",
|
||||
"--no-lockfile", "--non-interactive", "--pure-lockfile",
|
||||
]),
|
||||
};
|
||||
const lifecycleOptionsWithValue: Readonly<
|
||||
Record<PackageManager, ReadonlySet<string>>
|
||||
> = {
|
||||
pnpm: new Set(["--child-concurrency", "--modules-dir", "--reporter"]),
|
||||
npm: new Set(["--include", "--install-strategy", "--omit"]),
|
||||
yarn: new Set(["--mode", "--modules-folder", "--production"]),
|
||||
};
|
||||
const knownBuiltinCommands: Readonly<Record<PackageManager, ReadonlySet<string>>> = {
|
||||
pnpm: new Set([
|
||||
"audit", "config", "deploy", "dlx", "exec", "fetch", "help", "list", "ls",
|
||||
"outdated", "root", "server", "setup", "store", "view", "why",
|
||||
]),
|
||||
npm: new Set([
|
||||
"access", "audit", "bugs", "cache", "completion", "config", "diff", "docs",
|
||||
"doctor", "exec", "explore", "fund", "help", "help-search", "hook", "init",
|
||||
"list", "login", "logout", "ls", "org", "outdated", "owner", "ping", "pkg",
|
||||
"prefix", "profile", "query", "repo", "root", "search", "star", "stars",
|
||||
"team", "token", "unstar", "version", "view", "whoami",
|
||||
]),
|
||||
yarn: new Set([
|
||||
"cache", "config", "constraints", "dedupe", "dlx", "exec", "help", "info",
|
||||
"npm", "plugin", "set", "stage", "version", "why",
|
||||
]),
|
||||
};
|
||||
const exactBareSafeBuiltinCommands: Readonly<
|
||||
Record<PackageManager, ReadonlySet<string>>
|
||||
> = {
|
||||
pnpm: new Set(["audit"]),
|
||||
npm: new Set(["audit"]),
|
||||
yarn: new Set(),
|
||||
};
|
||||
const npmImplicitScripts = new Set(["restart", "start", "stop", "test"]);
|
||||
|
||||
export function validatePackageScriptGraph(
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
entryScript: string,
|
||||
): string[] {
|
||||
const failures: string[] = [];
|
||||
const visiting = new Set<string>();
|
||||
const visited = new Set<string>();
|
||||
const stack: string[] = [];
|
||||
|
||||
const visit = (scriptName: string): void => {
|
||||
if (visiting.has(scriptName)) {
|
||||
const start = stack.indexOf(scriptName);
|
||||
failures.push(`package script cycle: ${[...stack.slice(start), scriptName].join(" -> ")}`);
|
||||
return;
|
||||
}
|
||||
if (visited.has(scriptName)) return;
|
||||
const command = scripts[scriptName];
|
||||
if (command === undefined) {
|
||||
failures.push(`package script missing: ${scriptName}`);
|
||||
return;
|
||||
}
|
||||
visiting.add(scriptName);
|
||||
stack.push(scriptName);
|
||||
if (/\bscripts\/run-ci-gate(?:\.[cm]?[jt]s)?\b/u.test(command)) {
|
||||
failures.push(`${scriptName} must not invoke the CI gate runner`);
|
||||
}
|
||||
const parsed = parseManagerCommands(command, scripts);
|
||||
if (parsed.unsupportedManagerSyntax) {
|
||||
failures.push(`package script manager invocation is not safely parseable: ${scriptName}`);
|
||||
}
|
||||
for (const dependency of parsed.dependencies) {
|
||||
if (dependency === "ci:gate") {
|
||||
failures.push(`${scriptName} must not invoke ci:gate`);
|
||||
} else if (!(dependency in scripts)) {
|
||||
failures.push(`package script missing: ${scriptName} -> ${dependency}`);
|
||||
} else {
|
||||
visit(dependency);
|
||||
}
|
||||
}
|
||||
stack.pop();
|
||||
visiting.delete(scriptName);
|
||||
visited.add(scriptName);
|
||||
};
|
||||
|
||||
visit(entryScript);
|
||||
return [...new Set(failures)];
|
||||
}
|
||||
|
||||
export function validateInstallScriptPolicy(
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
entryScripts: readonly string[],
|
||||
): string[] {
|
||||
const failures: string[] = [];
|
||||
const visited = new Set<string>();
|
||||
const visit = (scriptName: string): void => {
|
||||
if (visited.has(scriptName)) return;
|
||||
visited.add(scriptName);
|
||||
const command = scripts[scriptName];
|
||||
if (command === undefined) {
|
||||
failures.push(`package script missing: ${scriptName}`);
|
||||
return;
|
||||
}
|
||||
const parsed = parseManagerCommands(command, scripts);
|
||||
if (parsed.unsafeLifecycle || parsed.unsupportedManagerSyntax) {
|
||||
failures.push(
|
||||
`install-bearing package script must use --ignore-scripts: ${scriptName}`,
|
||||
);
|
||||
}
|
||||
for (const dependency of parsed.dependencies) {
|
||||
if (dependency !== "ci:gate") visit(dependency);
|
||||
}
|
||||
};
|
||||
for (const entryScript of entryScripts) visit(entryScript);
|
||||
return [...new Set(failures)];
|
||||
}
|
||||
|
||||
export function validateNpmScopeEnvironment(
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
): string[] {
|
||||
return Object.keys(environment)
|
||||
.filter((name) => npmDispatchScopeEnvironmentNames.has(name.toLowerCase()))
|
||||
.map((name) => `npm scope environment is not allowed: ${name}`);
|
||||
}
|
||||
|
||||
function parseManagerCommands(
|
||||
command: string,
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
): ManagerParseResult {
|
||||
const tokenized = tokenizeShellSegments(command);
|
||||
const dependencies: string[] = [];
|
||||
let unsafeLifecycle = false;
|
||||
let unsupportedManagerSyntax = false;
|
||||
if (!tokenized) {
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([]),
|
||||
unsafeLifecycle: false,
|
||||
unsupportedManagerSyntax: containsManagerReference(command),
|
||||
});
|
||||
}
|
||||
unsupportedManagerSyntax ||= tokenized.unsupportedControl && containsManagerReference(command);
|
||||
const npmScopeEnvironmentState: ShellNpmScopeEnvironmentState = {
|
||||
autoExport: false,
|
||||
forbidden: false,
|
||||
uncertain: false,
|
||||
};
|
||||
for (const segment of tokenized.segments) {
|
||||
const { tokens, expansionTokens } = segment;
|
||||
updateShellNpmScopeEnvironmentState(segment, npmScopeEnvironmentState);
|
||||
for (let index = 0; index < tokens.length; index += 1) {
|
||||
const token = tokens[index]!;
|
||||
if (token === "corepack") {
|
||||
if (hasUnsafeManagerCommandPrefix(tokens, expansionTokens, index)) {
|
||||
unsupportedManagerSyntax = true;
|
||||
break;
|
||||
}
|
||||
const wrapped = tokens[index + 1];
|
||||
if (!wrapped || !isPackageManager(wrapped)) {
|
||||
unsupportedManagerSyntax = true;
|
||||
break;
|
||||
}
|
||||
const parsed = parseManagerInvocation(
|
||||
wrapped,
|
||||
tokens,
|
||||
expansionTokens,
|
||||
index + 2,
|
||||
scripts,
|
||||
hasUnsafeNpmScopeEnvironment(
|
||||
npmScopeEnvironmentState,
|
||||
tokens,
|
||||
expansionTokens,
|
||||
index,
|
||||
),
|
||||
);
|
||||
dependencies.push(...parsed.dependencies);
|
||||
unsafeLifecycle ||= parsed.unsafeLifecycle;
|
||||
unsupportedManagerSyntax ||= parsed.unsupportedManagerSyntax;
|
||||
break;
|
||||
}
|
||||
if (isPackageManager(token)) {
|
||||
if (hasUnsafeManagerCommandPrefix(tokens, expansionTokens, index)) {
|
||||
unsupportedManagerSyntax = true;
|
||||
break;
|
||||
}
|
||||
const parsed = parseManagerInvocation(
|
||||
token,
|
||||
tokens,
|
||||
expansionTokens,
|
||||
index + 1,
|
||||
scripts,
|
||||
hasUnsafeNpmScopeEnvironment(
|
||||
npmScopeEnvironmentState,
|
||||
tokens,
|
||||
expansionTokens,
|
||||
index,
|
||||
),
|
||||
);
|
||||
dependencies.push(...parsed.dependencies);
|
||||
unsafeLifecycle ||= parsed.unsafeLifecycle;
|
||||
unsupportedManagerSyntax ||= parsed.unsupportedManagerSyntax;
|
||||
break;
|
||||
}
|
||||
if (containsManagerReference(token)) {
|
||||
unsupportedManagerSyntax = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([...new Set(dependencies)]),
|
||||
unsafeLifecycle,
|
||||
unsupportedManagerSyntax,
|
||||
});
|
||||
}
|
||||
|
||||
function parseManagerInvocation(
|
||||
manager: PackageManager,
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
start: number,
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
hasNpmScopeEnvironment: boolean,
|
||||
): ManagerParseResult {
|
||||
let cursor = start;
|
||||
let changesManifestScope = false;
|
||||
let hasNpmConfigAuthority = false;
|
||||
let consumedManagerSyntax = false;
|
||||
const suppression: SuppressionState = {
|
||||
effective: undefined,
|
||||
contradictory: false,
|
||||
malformed: false,
|
||||
};
|
||||
while (cursor < tokens.length && tokens[cursor]!.startsWith("-")) {
|
||||
consumedManagerSyntax = true;
|
||||
const option = tokens[cursor]!;
|
||||
const parsedSuppression = consumeSuppressionOption(
|
||||
manager,
|
||||
tokens,
|
||||
cursor,
|
||||
suppression,
|
||||
);
|
||||
if (parsedSuppression.recognized) {
|
||||
if (parsedSuppression.unsupported) return unsupportedResult();
|
||||
cursor = parsedSuppression.nextIndex;
|
||||
continue;
|
||||
}
|
||||
const equals = option.indexOf("=");
|
||||
const name = equals < 0 ? option : option.slice(0, equals);
|
||||
if (managerOptionsWithValue.has(name)) {
|
||||
changesManifestScope ||= manifestScopeOptions[manager].has(name);
|
||||
hasNpmConfigAuthority ||=
|
||||
manager === "npm" && npmIndirectConfigAuthorityOptions.has(name);
|
||||
if (equals >= 0) {
|
||||
if (option.slice(equals + 1).length === 0) return unsupportedResult();
|
||||
} else {
|
||||
cursor += 1;
|
||||
if (cursor >= tokens.length || tokens[cursor]!.startsWith("-")) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
}
|
||||
} else if (managerBooleanOptions.has(name)) {
|
||||
if (equals >= 0 && !/^(?:true|false)$/u.test(option.slice(equals + 1))) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
} else if (option !== "--") {
|
||||
return unsupportedResult();
|
||||
}
|
||||
cursor += 1;
|
||||
}
|
||||
const subcommand = tokens[cursor];
|
||||
if (!subcommand) return unsupportedResult();
|
||||
if (manager === "npm" && (hasNpmScopeEnvironment || hasNpmConfigAuthority)) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
const argumentsAfterCommand = tokens.slice(cursor + 1);
|
||||
if (subcommand === "run" || subcommand === "run-script") {
|
||||
const dependency = argumentsAfterCommand[0];
|
||||
if (!dependency || dependency.startsWith("-")) return unsupportedResult();
|
||||
if (changesManifestScope) return unsupportedResult();
|
||||
if (
|
||||
manager === "npm" &&
|
||||
(expansionTokens.slice(start, cursor + 2).some(Boolean) ||
|
||||
!areNpmScriptDispatchArgumentsSupported(
|
||||
argumentsAfterCommand.slice(1),
|
||||
expansionTokens.slice(cursor + 2),
|
||||
suppression,
|
||||
))
|
||||
) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
return manager === "npm"
|
||||
? npmScriptDependencyResult(dependency, scripts, suppression)
|
||||
: dependencyResult(dependency);
|
||||
}
|
||||
const canonicalSubcommand = managerBuiltinAliases[manager].get(subcommand) ?? subcommand;
|
||||
if (unsupportedBuiltinDispatchers[manager].has(canonicalSubcommand)) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
if (lifecycleMutationCommands.has(canonicalSubcommand)) {
|
||||
const lifecycleArgumentsSupported = parseLifecycleArguments(
|
||||
manager,
|
||||
argumentsAfterCommand,
|
||||
suppression,
|
||||
);
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([]),
|
||||
unsafeLifecycle:
|
||||
!lifecycleArgumentsSupported || !hasEffectiveLifecycleSuppression(suppression),
|
||||
unsupportedManagerSyntax: !lifecycleArgumentsSupported,
|
||||
});
|
||||
}
|
||||
if (knownBuiltinCommands[manager].has(canonicalSubcommand)) {
|
||||
return exactBareSafeBuiltinCommands[manager].has(canonicalSubcommand) &&
|
||||
!consumedManagerSyntax &&
|
||||
argumentsAfterCommand.length === 0
|
||||
? emptyResult()
|
||||
: unsupportedResult();
|
||||
}
|
||||
const isKnownRootScript = Object.prototype.hasOwnProperty.call(scripts, subcommand);
|
||||
const supportsImplicit = /^[A-Za-z0-9:_-]+$/u.test(subcommand) && (
|
||||
((manager === "pnpm" || manager === "yarn") && isKnownRootScript) ||
|
||||
(manager === "npm" && npmImplicitScripts.has(subcommand))
|
||||
);
|
||||
if (supportsImplicit) {
|
||||
if (changesManifestScope) return unsupportedResult();
|
||||
if (
|
||||
manager === "npm" &&
|
||||
(expansionTokens.slice(start, cursor + 1).some(Boolean) ||
|
||||
!areNpmScriptDispatchArgumentsSupported(
|
||||
argumentsAfterCommand,
|
||||
expansionTokens.slice(cursor + 1),
|
||||
suppression,
|
||||
))
|
||||
) {
|
||||
return unsupportedResult();
|
||||
}
|
||||
return manager === "npm"
|
||||
? npmScriptDependencyResult(subcommand, scripts, suppression)
|
||||
: dependencyResult(subcommand);
|
||||
}
|
||||
return unsupportedResult();
|
||||
}
|
||||
|
||||
function areNpmScriptDispatchArgumentsSupported(
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
suppression: SuppressionState,
|
||||
): boolean {
|
||||
let index = 0;
|
||||
while (index < tokens.length) {
|
||||
const token = tokens[index]!;
|
||||
if (token === "--") return true;
|
||||
if (expansionTokens[index]) return false;
|
||||
if (!token.startsWith("-")) {
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
|
||||
const parsedSuppression = consumeSuppressionOption(
|
||||
"npm",
|
||||
tokens,
|
||||
index,
|
||||
suppression,
|
||||
);
|
||||
if (parsedSuppression.recognized) {
|
||||
if (parsedSuppression.unsupported) return false;
|
||||
index = parsedSuppression.nextIndex;
|
||||
continue;
|
||||
}
|
||||
|
||||
const equals = token.indexOf("=");
|
||||
const name = equals < 0 ? token : token.slice(0, equals);
|
||||
const isShortWorkspaceOption = token === "-w" || /^-w(?:=)?.+/u.test(token);
|
||||
if (npmScriptDispatchScopeOptions.has(name) || isShortWorkspaceOption) {
|
||||
return false;
|
||||
}
|
||||
if (!npmScriptDispatchBooleanOptions.has(name)) return false;
|
||||
if (equals >= 0 && !/^(?:true|false)$/u.test(token.slice(equals + 1))) {
|
||||
return false;
|
||||
}
|
||||
index += 1;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function hasUnsafeNpmScopeEnvironment(
|
||||
state: Readonly<ShellNpmScopeEnvironmentState>,
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
commandIndex: number,
|
||||
): boolean {
|
||||
return state.forbidden || state.uncertain ||
|
||||
hasUnsafeImmediateNpmScopeEnvironment(tokens, expansionTokens, commandIndex);
|
||||
}
|
||||
|
||||
function hasUnsafeManagerCommandPrefix(
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
commandIndex: number,
|
||||
): boolean {
|
||||
const prefix = parseShellCommandPrefix(tokens, expansionTokens);
|
||||
if (prefix.uncertain) return true;
|
||||
let cursor = prefix.commandIndex;
|
||||
if (cursor === commandIndex) return false;
|
||||
if (cursor > commandIndex ||
|
||||
!isEnvironmentCommand(tokens[cursor], expansionTokens[cursor] ?? false)) {
|
||||
return true;
|
||||
}
|
||||
return parseEnvironmentCommandPrefix(
|
||||
tokens,
|
||||
expansionTokens,
|
||||
cursor,
|
||||
commandIndex,
|
||||
).uncertain;
|
||||
}
|
||||
|
||||
function hasUnsafeImmediateNpmScopeEnvironment(
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
commandIndex: number,
|
||||
): boolean {
|
||||
const prefix = parseShellCommandPrefix(tokens, expansionTokens);
|
||||
if (prefix.uncertain || prefix.assignments.some(
|
||||
({ name }) => name !== null && isNpmScopeEnvironmentName(name),
|
||||
)) return true;
|
||||
let cursor = prefix.commandIndex;
|
||||
if (cursor === commandIndex) return false;
|
||||
if (!isEnvironmentCommand(tokens[cursor], expansionTokens[cursor] ?? false)) return false;
|
||||
const environmentPrefix = parseEnvironmentCommandPrefix(
|
||||
tokens,
|
||||
expansionTokens,
|
||||
cursor,
|
||||
commandIndex,
|
||||
);
|
||||
return environmentPrefix.uncertain || environmentPrefix.assignmentNames.some(
|
||||
(name) => isNpmScopeEnvironmentName(name),
|
||||
);
|
||||
}
|
||||
|
||||
function parseEnvironmentCommandPrefix(
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
start: number,
|
||||
commandIndex: number,
|
||||
): EnvironmentCommandPrefix {
|
||||
const assignmentNames: string[] = [];
|
||||
let cursor = start + 1;
|
||||
let uncertain = false;
|
||||
|
||||
while (cursor < commandIndex && tokens[cursor]!.startsWith("-")) {
|
||||
const option = tokens[cursor]!;
|
||||
if (expansionTokens[cursor]) uncertain = true;
|
||||
if (option === "--") {
|
||||
cursor += 1;
|
||||
break;
|
||||
}
|
||||
if (option === "-i" || option === "--ignore-environment") {
|
||||
cursor += 1;
|
||||
continue;
|
||||
}
|
||||
if (option === "-u" || option === "--unset") {
|
||||
cursor += 1;
|
||||
if (cursor >= commandIndex || tokens[cursor]!.startsWith("-")) {
|
||||
uncertain = true;
|
||||
break;
|
||||
}
|
||||
uncertain ||= expansionTokens[cursor] ?? false;
|
||||
cursor += 1;
|
||||
continue;
|
||||
}
|
||||
if (/^--unset=.+/u.test(option)) {
|
||||
cursor += 1;
|
||||
continue;
|
||||
}
|
||||
uncertain = true;
|
||||
cursor += 1;
|
||||
}
|
||||
|
||||
while (cursor < commandIndex) {
|
||||
const token = tokens[cursor]!;
|
||||
if (hasDynamicAssignmentName(token, expansionTokens[cursor] ?? false)) {
|
||||
uncertain = true;
|
||||
}
|
||||
const assignmentName = parseEnvironmentAssignmentName(token);
|
||||
if (assignmentName) assignmentNames.push(assignmentName);
|
||||
else uncertain = true;
|
||||
cursor += 1;
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
assignmentNames: Object.freeze(assignmentNames),
|
||||
uncertain,
|
||||
});
|
||||
}
|
||||
|
||||
function parseShellCommandPrefix(
|
||||
tokens: readonly string[],
|
||||
expansionTokens: readonly boolean[],
|
||||
): ShellCommandPrefix {
|
||||
const assignments: Array<{
|
||||
dynamicName: boolean;
|
||||
name: string | null;
|
||||
}> = [];
|
||||
let cursor = 0;
|
||||
let uncertain = false;
|
||||
while (cursor < tokens.length) {
|
||||
const token = tokens[cursor]!;
|
||||
const name = parseAssignmentName(token);
|
||||
const dynamicName = hasDynamicAssignmentName(
|
||||
token,
|
||||
expansionTokens[cursor] ?? false,
|
||||
);
|
||||
if (!name && !dynamicName) break;
|
||||
assignments.push({ dynamicName, name });
|
||||
uncertain ||= dynamicName;
|
||||
cursor += 1;
|
||||
}
|
||||
|
||||
while (cursor < tokens.length) {
|
||||
const wrapper = tokens[cursor];
|
||||
if (expansionTokens[cursor]) {
|
||||
uncertain = true;
|
||||
break;
|
||||
}
|
||||
if (wrapper !== "command" && wrapper !== "exec") break;
|
||||
cursor += 1;
|
||||
while (cursor < tokens.length && tokens[cursor]!.startsWith("-")) {
|
||||
const option = tokens[cursor]!;
|
||||
if (option === "--") {
|
||||
cursor += 1;
|
||||
break;
|
||||
}
|
||||
if (wrapper === "command" && option === "-p") {
|
||||
cursor += 1;
|
||||
continue;
|
||||
}
|
||||
uncertain = true;
|
||||
cursor += 1;
|
||||
if (wrapper === "exec" && option === "-a" && cursor < tokens.length) {
|
||||
cursor += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
if (expansionTokens[cursor]) uncertain = true;
|
||||
return Object.freeze({
|
||||
assignments: Object.freeze(assignments.map((assignment) => Object.freeze(assignment))),
|
||||
commandIndex: cursor,
|
||||
uncertain,
|
||||
});
|
||||
}
|
||||
|
||||
function updateShellNpmScopeEnvironmentState(
|
||||
segment: TokenizedShellSegment,
|
||||
state: ShellNpmScopeEnvironmentState,
|
||||
): void {
|
||||
const { tokens, expansionTokens } = segment;
|
||||
const prefix = parseShellCommandPrefix(tokens, expansionTokens);
|
||||
state.uncertain ||= prefix.uncertain;
|
||||
const command = tokens[prefix.commandIndex];
|
||||
if (!command) {
|
||||
for (const assignment of prefix.assignments) {
|
||||
if (state.autoExport && assignment.name &&
|
||||
isNpmScopeEnvironmentName(assignment.name)) {
|
||||
state.forbidden = true;
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === "eval" || command === "." || command === "source") {
|
||||
state.uncertain = true;
|
||||
return;
|
||||
}
|
||||
if (command === "unset" || command === "typeset" || command === "declare" ||
|
||||
command === "local" || command === "readonly") {
|
||||
state.uncertain = true;
|
||||
return;
|
||||
}
|
||||
if (command === "set") {
|
||||
if (tokens.slice(prefix.commandIndex + 1).includes("-a")) state.autoExport = true;
|
||||
if (tokens.slice(prefix.commandIndex + 1).includes("+a")) {
|
||||
state.autoExport = false;
|
||||
state.uncertain = true;
|
||||
}
|
||||
return;
|
||||
}
|
||||
if (command === "export") {
|
||||
let cursor = prefix.commandIndex + 1;
|
||||
for (; cursor < tokens.length; cursor += 1) {
|
||||
const token = tokens[cursor]!;
|
||||
if (token === "--") continue;
|
||||
if (token === "-n" || token.startsWith("-")) {
|
||||
state.uncertain = true;
|
||||
continue;
|
||||
}
|
||||
const assignmentName = parseAssignmentName(token);
|
||||
const bareName = /^[A-Za-z_][A-Za-z0-9_]*$/u.test(token) ? token : null;
|
||||
if (assignmentName || bareName) {
|
||||
if (isNpmScopeEnvironmentName(assignmentName ?? bareName!)) {
|
||||
state.forbidden = true;
|
||||
}
|
||||
} else if (hasDynamicAssignmentName(token, expansionTokens[cursor] ?? false) ||
|
||||
expansionTokens[cursor]) {
|
||||
state.uncertain = true;
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
function isEnvironmentCommand(token: string | undefined, hasExpansion: boolean): boolean {
|
||||
if (!token || hasExpansion) return false;
|
||||
return token.split("/").at(-1) === "env";
|
||||
}
|
||||
|
||||
function parseEnvironmentAssignmentName(token: string): string | null {
|
||||
const equals = token.indexOf("=");
|
||||
return equals > 0 ? token.slice(0, equals) : null;
|
||||
}
|
||||
|
||||
function isNpmScopeEnvironmentName(name: string): boolean {
|
||||
return npmDispatchScopeEnvironmentNames.has(name.toLowerCase());
|
||||
}
|
||||
|
||||
function hasDynamicAssignmentName(token: string, hasExpansion: boolean): boolean {
|
||||
const equals = token.indexOf("=");
|
||||
return hasExpansion && equals > 0 && parseAssignmentName(token) === null;
|
||||
}
|
||||
|
||||
function parseAssignmentName(token: string): string | null {
|
||||
return /^([A-Za-z_][A-Za-z0-9_]*)=/u.exec(token)?.[1] ?? null;
|
||||
}
|
||||
|
||||
function parseLifecycleArguments(
|
||||
manager: PackageManager,
|
||||
tokens: readonly string[],
|
||||
suppression: SuppressionState,
|
||||
): boolean {
|
||||
let cursor = 0;
|
||||
while (cursor < tokens.length) {
|
||||
const token = tokens[cursor]!;
|
||||
if (!token.startsWith("-")) {
|
||||
cursor += 1;
|
||||
continue;
|
||||
}
|
||||
const parsedSuppression = consumeSuppressionOption(
|
||||
manager,
|
||||
tokens,
|
||||
cursor,
|
||||
suppression,
|
||||
);
|
||||
if (parsedSuppression.recognized) {
|
||||
if (parsedSuppression.unsupported) return false;
|
||||
cursor = parsedSuppression.nextIndex;
|
||||
continue;
|
||||
}
|
||||
const parsedOption = consumeAllowedLifecycleOption(manager, tokens, cursor);
|
||||
if (parsedOption === null) return false;
|
||||
cursor = parsedOption;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function consumeSuppressionOption(
|
||||
manager: PackageManager,
|
||||
tokens: readonly string[],
|
||||
index: number,
|
||||
state: SuppressionState,
|
||||
): Readonly<{ recognized: boolean; unsupported: boolean; nextIndex: number }> {
|
||||
const token = tokens[index]!;
|
||||
if (token === "--no-ignore-scripts") {
|
||||
recordSuppression(state, false);
|
||||
return { recognized: true, unsupported: false, nextIndex: index + 1 };
|
||||
}
|
||||
const equalsForms = ["--ignore-scripts=", "--config.ignore-scripts="] as const;
|
||||
for (const prefix of equalsForms) {
|
||||
if (!token.startsWith(prefix)) continue;
|
||||
if (prefix.startsWith("--config.") && manager !== "pnpm") {
|
||||
state.malformed = true;
|
||||
return { recognized: true, unsupported: true, nextIndex: index + 1 };
|
||||
}
|
||||
const raw = token.slice(prefix.length);
|
||||
if (raw !== "true" && raw !== "false") {
|
||||
state.malformed = true;
|
||||
return { recognized: true, unsupported: true, nextIndex: index + 1 };
|
||||
}
|
||||
recordSuppression(state, raw === "true");
|
||||
return { recognized: true, unsupported: false, nextIndex: index + 1 };
|
||||
}
|
||||
if (token !== "--ignore-scripts" && token !== "--config.ignore-scripts") {
|
||||
return { recognized: false, unsupported: false, nextIndex: index };
|
||||
}
|
||||
if (token === "--config.ignore-scripts" && manager !== "pnpm") {
|
||||
state.malformed = true;
|
||||
return { recognized: true, unsupported: true, nextIndex: index + 1 };
|
||||
}
|
||||
const next = tokens[index + 1];
|
||||
if (next === "true" || next === "false") {
|
||||
const supportsSplitValue = manager === "npm" || manager === "pnpm";
|
||||
if (!supportsSplitValue) {
|
||||
state.malformed = true;
|
||||
return { recognized: true, unsupported: true, nextIndex: index + 2 };
|
||||
}
|
||||
recordSuppression(state, next === "true");
|
||||
return { recognized: true, unsupported: false, nextIndex: index + 2 };
|
||||
}
|
||||
recordSuppression(state, true);
|
||||
return { recognized: true, unsupported: false, nextIndex: index + 1 };
|
||||
}
|
||||
|
||||
function recordSuppression(
|
||||
state: SuppressionState,
|
||||
value: boolean,
|
||||
): void {
|
||||
if (state.effective !== undefined && state.effective !== value) {
|
||||
state.contradictory = true;
|
||||
}
|
||||
state.effective = value;
|
||||
}
|
||||
|
||||
function hasEffectiveLifecycleSuppression(state: SuppressionState): boolean {
|
||||
return state.effective === true && !state.contradictory && !state.malformed;
|
||||
}
|
||||
|
||||
function consumeAllowedLifecycleOption(
|
||||
manager: PackageManager,
|
||||
tokens: readonly string[],
|
||||
index: number,
|
||||
): number | null {
|
||||
const option = tokens[index]!;
|
||||
const equals = option.indexOf("=");
|
||||
const name = equals < 0 ? option : option.slice(0, equals);
|
||||
const booleanOption =
|
||||
managerBooleanOptions.has(name) || lifecycleBooleanOptions[manager].has(name);
|
||||
if (booleanOption) {
|
||||
if (equals >= 0 && !/^(?:true|false)$/u.test(option.slice(equals + 1))) return null;
|
||||
return index + 1;
|
||||
}
|
||||
const valuedOption =
|
||||
managerOptionsWithValue.has(name) || lifecycleOptionsWithValue[manager].has(name);
|
||||
if (!valuedOption) return null;
|
||||
if (equals >= 0) return option.slice(equals + 1).length > 0 ? index + 1 : null;
|
||||
const value = tokens[index + 1];
|
||||
if (!value || value.startsWith("-")) return null;
|
||||
return index + 2;
|
||||
}
|
||||
|
||||
function dependencyResult(dependency: string): ManagerParseResult {
|
||||
return dependenciesResult([dependency]);
|
||||
}
|
||||
|
||||
function npmScriptDependencyResult(
|
||||
dependency: string,
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
suppression: SuppressionState,
|
||||
): ManagerParseResult {
|
||||
if (hasEffectiveLifecycleSuppression(suppression)) {
|
||||
return dependenciesResult([dependency]);
|
||||
}
|
||||
return dependenciesResult(
|
||||
[`pre${dependency}`, dependency, `post${dependency}`]
|
||||
.filter((scriptName) => scriptName === dependency || scriptName in scripts),
|
||||
);
|
||||
}
|
||||
|
||||
function dependenciesResult(dependencies: readonly string[]): ManagerParseResult {
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([...dependencies]),
|
||||
unsafeLifecycle: false,
|
||||
unsupportedManagerSyntax: false,
|
||||
});
|
||||
}
|
||||
|
||||
function emptyResult(): ManagerParseResult {
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([]),
|
||||
unsafeLifecycle: false,
|
||||
unsupportedManagerSyntax: false,
|
||||
});
|
||||
}
|
||||
|
||||
function unsupportedResult(): ManagerParseResult {
|
||||
return Object.freeze({
|
||||
dependencies: Object.freeze([]),
|
||||
unsafeLifecycle: false,
|
||||
unsupportedManagerSyntax: true,
|
||||
});
|
||||
}
|
||||
|
||||
function isPackageManager(value: string): value is PackageManager {
|
||||
return managerNames.has(value as PackageManager);
|
||||
}
|
||||
|
||||
function containsManagerReference(value: string): boolean {
|
||||
return /(?:^|[^A-Za-z0-9_-])(?:corepack|pnpm|npm|yarn)(?:[^A-Za-z0-9_-]|$)/u
|
||||
.test(value);
|
||||
}
|
||||
|
||||
function tokenizeShellSegments(command: string): Readonly<{
|
||||
segments: readonly TokenizedShellSegment[];
|
||||
unsupportedControl: boolean;
|
||||
}> | null {
|
||||
const segments: Array<{ tokens: string[]; expansionTokens: boolean[] }> = [
|
||||
{ tokens: [], expansionTokens: [] },
|
||||
];
|
||||
let token = "";
|
||||
let tokenHasExpansion = false;
|
||||
let quote: "'" | '"' | null = null;
|
||||
let escaping = false;
|
||||
let unsupportedControl = false;
|
||||
const pushToken = (): void => {
|
||||
if (token.length > 0) {
|
||||
segments.at(-1)!.tokens.push(token);
|
||||
segments.at(-1)!.expansionTokens.push(tokenHasExpansion);
|
||||
}
|
||||
token = "";
|
||||
tokenHasExpansion = false;
|
||||
};
|
||||
const pushSegment = (): void => {
|
||||
pushToken();
|
||||
if (segments.at(-1)!.tokens.length > 0) {
|
||||
segments.push({ tokens: [], expansionTokens: [] });
|
||||
}
|
||||
};
|
||||
for (let index = 0; index < command.length; index += 1) {
|
||||
const character = command[index]!;
|
||||
if (escaping) {
|
||||
token += character;
|
||||
escaping = false;
|
||||
continue;
|
||||
}
|
||||
if (character === "\\" && quote !== "'") {
|
||||
escaping = true;
|
||||
continue;
|
||||
}
|
||||
if (quote) {
|
||||
if (character === quote) quote = null;
|
||||
else {
|
||||
if (quote === '"' && character === "$") tokenHasExpansion = true;
|
||||
token += character;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (character === "'" || character === '"') {
|
||||
quote = character;
|
||||
continue;
|
||||
}
|
||||
if (character === "`" || (character === "$" && command[index + 1] === "(")) {
|
||||
unsupportedControl = true;
|
||||
if (character === "$") tokenHasExpansion = true;
|
||||
token += character;
|
||||
continue;
|
||||
}
|
||||
if (character === "$" || character === "*" || character === "?" || character === "[") {
|
||||
tokenHasExpansion = true;
|
||||
}
|
||||
if (character === "#") {
|
||||
unsupportedControl = true;
|
||||
pushToken();
|
||||
while (
|
||||
index + 1 < command.length &&
|
||||
command[index + 1] !== "\n" &&
|
||||
command[index + 1] !== "\r"
|
||||
) {
|
||||
index += 1;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (character === "<" || character === ">" || character === "(" || character === ")") {
|
||||
unsupportedControl = true;
|
||||
token += character;
|
||||
continue;
|
||||
}
|
||||
if (/\s/u.test(character)) {
|
||||
pushToken();
|
||||
if (character === "\n" || character === "\r") pushSegment();
|
||||
continue;
|
||||
}
|
||||
if (character === ";" || character === "|" || character === "&") {
|
||||
pushSegment();
|
||||
if (command[index + 1] === character) index += 1;
|
||||
continue;
|
||||
}
|
||||
token += character;
|
||||
}
|
||||
if (quote || escaping) return null;
|
||||
pushToken();
|
||||
return Object.freeze({
|
||||
segments: Object.freeze(
|
||||
segments
|
||||
.filter((segment) => segment.tokens.length > 0)
|
||||
.map((segment) => Object.freeze({
|
||||
tokens: Object.freeze(segment.tokens),
|
||||
expansionTokens: Object.freeze(segment.expansionTokens),
|
||||
})),
|
||||
),
|
||||
unsupportedControl,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import { mkdirSync, mkdtempSync } from "node:fs";
|
||||
|
||||
/**
|
||||
* Creation modes that must not depend on the caller's ambient umask.
|
||||
*
|
||||
* `mkdir(path, { mode: 0o700 })` and `open(path, ..., 0o600)` are requests, not
|
||||
* guarantees: the kernel subtracts the process umask from every one of them. A
|
||||
* runner hardened with `umask 0777` therefore produces directories nobody can
|
||||
* enter and files nobody can read, and the failure surfaces far from its cause
|
||||
* — as `tar` failing to mkdir a nested path, or as EACCES opening a staging
|
||||
* leaf this process created moments earlier.
|
||||
*
|
||||
* Release evidence has to be exactly private, so the mode is pinned rather than
|
||||
* inherited. The pin is held across a synchronous call only: nothing else in
|
||||
* this process can interleave, so the global umask is never observably changed.
|
||||
*/
|
||||
const PRIVATE_UMASK = 0o077;
|
||||
|
||||
export function withPrivateUmask<T>(operation: () => T): T {
|
||||
const previous = process.umask(PRIVATE_UMASK);
|
||||
try {
|
||||
return operation();
|
||||
} finally {
|
||||
process.umask(previous);
|
||||
}
|
||||
}
|
||||
|
||||
/** Creates a uniquely named private directory under `prefix`. */
|
||||
export function makePrivateTemporaryDirectory(prefix: string): string {
|
||||
return withPrivateUmask(() => mkdtempSync(prefix));
|
||||
}
|
||||
|
||||
/** Creates `target` privately, failing if it already exists. */
|
||||
export function makePrivateDirectory(target: string): void {
|
||||
withPrivateUmask(() => mkdirSync(target, { mode: 0o700 }));
|
||||
}
|
||||
@@ -0,0 +1,721 @@
|
||||
import {
|
||||
createHash,
|
||||
createPublicKey,
|
||||
randomBytes as cryptoRandomBytes,
|
||||
} from "node:crypto";
|
||||
import { constants } from "node:fs";
|
||||
import {
|
||||
lstat,
|
||||
open,
|
||||
readdir,
|
||||
rm,
|
||||
rmdir,
|
||||
stat,
|
||||
} from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
PROMOTED_FILE_NAMES,
|
||||
type PromotedFileName,
|
||||
} from "../contracts/promotion-artifacts.ts";
|
||||
import {
|
||||
evaluatePromotionEvidence,
|
||||
assertDistinctProviderTrust,
|
||||
providerPublicKeyFingerprint,
|
||||
providerVerificationArtifactSchema,
|
||||
PROMOTION_VERIFIER_ID,
|
||||
PROMOTION_VERIFIER_VERSION,
|
||||
provenanceProviderAttestationSchema,
|
||||
trustPolicySha256,
|
||||
vulnerabilityProviderReportSchema,
|
||||
type ProviderTrust,
|
||||
} from "./provider-evidence.ts";
|
||||
import { verifyExactPromotionBundle } from "./exact-promotion-bundle.ts";
|
||||
import {
|
||||
captureCiCandidateArchive,
|
||||
withVerifiedCapturedCandidate,
|
||||
} from "./ci-candidate-archive.ts";
|
||||
import { verifyArchivedLocalEvidence } from "./local-release-evidence.ts";
|
||||
import { readBoundedRegularFile } from "./ci-artifact-validator.ts";
|
||||
import { makePrivateDirectory } from "./private-filesystem.ts";
|
||||
|
||||
|
||||
export type StagedFile = Readonly<{
|
||||
name: PromotedFileName;
|
||||
bytes: Buffer;
|
||||
sha256: string;
|
||||
}>;
|
||||
|
||||
export type FinalizedPromotion = Readonly<{
|
||||
stagingRoot: string;
|
||||
cleanupToken: string;
|
||||
runnerTempIdentity: Readonly<{ dev: number; ino: number }>;
|
||||
stagingIdentity: Readonly<{ dev: number; ino: number }>;
|
||||
files: readonly Readonly<{ name: PromotedFileName; sha256: string }>[];
|
||||
}>;
|
||||
|
||||
export async function finalizeVerifiedPromotion(input: Readonly<{
|
||||
repositoryRoot: string;
|
||||
archivePath: string;
|
||||
expectedArchiveSha256: string;
|
||||
vulnerabilityReportPath: string;
|
||||
provenanceAttestationPath: string;
|
||||
vulnerabilityPublicKeyPath: string;
|
||||
vulnerabilityKeyId: string;
|
||||
provenancePublicKeyPath: string;
|
||||
provenanceKeyId: string;
|
||||
expectedRun: Readonly<{ id: string; attempt: number; sourceRevision: string }>;
|
||||
vulnerabilityInvocationNonce: string;
|
||||
provenanceInvocationNonce: string;
|
||||
runnerTempRoot: string;
|
||||
}>, dependencies: Readonly<{
|
||||
captureArchive?: typeof captureCiCandidateArchive;
|
||||
nowEpochMs?: () => number;
|
||||
randomBytes?: (bytes: number) => Buffer;
|
||||
afterCapture?: () => Promise<void>;
|
||||
beforePublish?: () => Promise<void>;
|
||||
afterStagingWrite?: () => Promise<void>;
|
||||
afterFileWrite?: (name: PromotedFileName) => Promise<void>;
|
||||
beforeSeal?: () => Promise<void>;
|
||||
afterMkdirBeforeOpen?: (stagingRoot: string) => Promise<void>;
|
||||
}> = {}): Promise<FinalizedPromotion> {
|
||||
const root = path.resolve(input.repositoryRoot);
|
||||
const capturedArchive = await (dependencies.captureArchive ?? captureCiCandidateArchive)({
|
||||
archivePath: input.archivePath,
|
||||
expectedSha256: input.expectedArchiveSha256,
|
||||
});
|
||||
const [vulnerabilityBytes, provenanceBytes, vulnerabilityKeyBytes, provenanceKeyBytes] =
|
||||
await Promise.all([
|
||||
capture(root, input.vulnerabilityReportPath, 16_777_216),
|
||||
capture(root, input.provenanceAttestationPath, 16_777_216),
|
||||
capture(root, input.vulnerabilityPublicKeyPath, 1_048_576),
|
||||
capture(root, input.provenancePublicKeyPath, 1_048_576),
|
||||
]);
|
||||
await dependencies.afterCapture?.();
|
||||
|
||||
const vulnerabilityTrust = capturedTrust(
|
||||
input.vulnerabilityKeyId,
|
||||
vulnerabilityKeyBytes,
|
||||
);
|
||||
const provenanceTrust = capturedTrust(
|
||||
input.provenanceKeyId,
|
||||
provenanceKeyBytes,
|
||||
);
|
||||
assertDistinctProviderTrust({ vulnerabilityTrust, provenanceTrust });
|
||||
const vulnerabilityReport = vulnerabilityProviderReportSchema.parse(
|
||||
parseJson(vulnerabilityBytes),
|
||||
);
|
||||
const provenanceAttestation = provenanceProviderAttestationSchema.parse(
|
||||
parseJson(provenanceBytes),
|
||||
);
|
||||
const nowEpochMs = dependencies.nowEpochMs ?? Date.now;
|
||||
|
||||
const generated = await withVerifiedCapturedCandidate({
|
||||
captured: capturedArchive,
|
||||
verify: async ({ extractionRoot, manifest }) => {
|
||||
const local = await verifyArchivedLocalEvidence({
|
||||
extractionRoot,
|
||||
expectedManifest: manifest,
|
||||
});
|
||||
if (local.status !== "PASS" || !local.identity) {
|
||||
throw new Error(
|
||||
`captured local evidence failed final verification: ${local.failures.join(", ")}`,
|
||||
);
|
||||
}
|
||||
if (local.identity.sourceRevision !== input.expectedRun.sourceRevision) {
|
||||
throw new Error("captured source revision differs from expected promotion revision");
|
||||
}
|
||||
const expected = {
|
||||
run: { id: input.expectedRun.id, attempt: input.expectedRun.attempt },
|
||||
source: {
|
||||
revision: local.identity.sourceRevision,
|
||||
sourceSetSha256: local.identity.sourceSetSha256,
|
||||
},
|
||||
candidate: {
|
||||
archiveSha256: capturedArchive.archiveSha256,
|
||||
bundleSha256: manifest.bundleSha256,
|
||||
distSha256: manifest.distSha256,
|
||||
lockfileSha256: manifest.lockfileSha256,
|
||||
},
|
||||
secretScanAttestation: {
|
||||
status: "PASS" as const,
|
||||
localEvidenceAssessmentSha256: local.identity.assessmentSha256,
|
||||
sourceSetSha256: local.identity.sourceSetSha256,
|
||||
policySha256: local.identity.secretScan.policySha256,
|
||||
sarifSha256: local.identity.secretScan.sarifSha256,
|
||||
scanInputSha256: local.identity.secretScan.scanInputSha256,
|
||||
},
|
||||
vulnerabilityInvocationNonce: input.vulnerabilityInvocationNonce,
|
||||
provenanceInvocationNonce: input.provenanceInvocationNonce,
|
||||
} as const;
|
||||
const reevaluated = evaluatePromotionEvidence({
|
||||
expected,
|
||||
localStatus: local.status,
|
||||
vulnerabilityReport,
|
||||
provenanceAttestation,
|
||||
vulnerabilityTrust,
|
||||
provenanceTrust,
|
||||
nowEpochMs,
|
||||
});
|
||||
if (reevaluated.status !== "PASS") {
|
||||
throw new Error(
|
||||
`captured provider evidence failed trusted revalidation: ${reevaluated.failures.join(", ")}`,
|
||||
);
|
||||
}
|
||||
const providerEvidence = {
|
||||
vulnerabilityReportSha256: sha256(vulnerabilityBytes),
|
||||
provenanceAttestationSha256: sha256(provenanceBytes),
|
||||
vulnerabilityInvocationNonce: input.vulnerabilityInvocationNonce,
|
||||
provenanceInvocationNonce: input.provenanceInvocationNonce,
|
||||
vulnerabilityKeyId: vulnerabilityTrust.keyId,
|
||||
vulnerabilityKeyFingerprint: vulnerabilityTrust.publicKeyFingerprint,
|
||||
provenanceKeyId: provenanceTrust.keyId,
|
||||
provenanceKeyFingerprint: provenanceTrust.publicKeyFingerprint,
|
||||
secretScanAttestation: expected.secretScanAttestation,
|
||||
} as const;
|
||||
const trustDigest = trustPolicySha256({ vulnerabilityTrust, provenanceTrust });
|
||||
const verifiedAt = new Date(nowEpochMs()).toISOString();
|
||||
const common = {
|
||||
schemaVersion: 3 as const,
|
||||
verifiedAt,
|
||||
status: "PASS" as const,
|
||||
verifier: {
|
||||
id: PROMOTION_VERIFIER_ID,
|
||||
version: PROMOTION_VERIFIER_VERSION,
|
||||
},
|
||||
run: expected.run,
|
||||
source: expected.source,
|
||||
candidate: expected.candidate,
|
||||
providerEvidence,
|
||||
trustPolicySha256: trustDigest,
|
||||
failures: [] as const,
|
||||
};
|
||||
const providerRecord = providerVerificationArtifactSchema.parse({
|
||||
...common,
|
||||
artifactType: "provider-verification",
|
||||
vulnerabilityStatus: reevaluated.vulnerabilityStatus,
|
||||
provenanceAttestationStatus: reevaluated.provenanceAttestationStatus,
|
||||
});
|
||||
const providerRecordBytes = canonicalJsonBytes(providerRecord);
|
||||
const promotionRecord = providerVerificationArtifactSchema.parse({
|
||||
...common,
|
||||
artifactType: "promotion-verification",
|
||||
localEvidenceStatus: local.status,
|
||||
localEvidenceAssessmentSha256: local.identity.assessmentSha256,
|
||||
providerVerificationSha256: sha256(providerRecordBytes),
|
||||
});
|
||||
return Object.freeze({
|
||||
providerRecordBytes,
|
||||
promotionRecordBytes: canonicalJsonBytes(promotionRecord),
|
||||
exactExpected: Object.freeze({
|
||||
run: expected.run,
|
||||
sourceRevision: expected.source.revision,
|
||||
sourceSetSha256: expected.source.sourceSetSha256,
|
||||
archiveSha256: expected.candidate.archiveSha256,
|
||||
bundleSha256: expected.candidate.bundleSha256,
|
||||
distSha256: expected.candidate.distSha256,
|
||||
lockfileSha256: expected.candidate.lockfileSha256,
|
||||
}),
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
const stagedFiles: readonly StagedFile[] = Object.freeze([
|
||||
staged("release-candidate.tar.gz", capturedArchive.bytes),
|
||||
staged("vulnerability-report.json", vulnerabilityBytes),
|
||||
staged("provenance-attestation.json", provenanceBytes),
|
||||
staged("provider-verification.json", generated.providerRecordBytes),
|
||||
staged("promotion-verification.json", generated.promotionRecordBytes),
|
||||
]);
|
||||
if (
|
||||
JSON.stringify(stagedFiles.map(({ name }) => name)) !==
|
||||
JSON.stringify(PROMOTED_FILE_NAMES)
|
||||
) {
|
||||
throw new Error("promotion exact-five canonical file order drift");
|
||||
}
|
||||
await dependencies.beforePublish?.();
|
||||
await verifyExactPromotionBundle(
|
||||
Object.fromEntries(stagedFiles.map(({ name, bytes }) => [name, bytes])),
|
||||
{
|
||||
vulnerabilityTrust,
|
||||
provenanceTrust,
|
||||
expected: generated.exactExpected,
|
||||
nowEpochMs,
|
||||
},
|
||||
);
|
||||
return publishPrivatePromotionStaging(
|
||||
input.runnerTempRoot,
|
||||
input.expectedRun,
|
||||
stagedFiles,
|
||||
dependencies.randomBytes ?? cryptoRandomBytes,
|
||||
dependencies.afterStagingWrite,
|
||||
dependencies.afterFileWrite,
|
||||
async (capturedFiles) => {
|
||||
await verifyExactPromotionBundle(
|
||||
capturedFiles,
|
||||
{
|
||||
vulnerabilityTrust,
|
||||
provenanceTrust,
|
||||
expected: generated.exactExpected,
|
||||
nowEpochMs,
|
||||
},
|
||||
);
|
||||
},
|
||||
dependencies.afterMkdirBeforeOpen,
|
||||
dependencies.beforeSeal,
|
||||
);
|
||||
}
|
||||
|
||||
export const stageVerifiedPromotion = finalizeVerifiedPromotion;
|
||||
|
||||
export async function cleanupFinalizedPromotion(input: Readonly<{
|
||||
runnerTempRoot: string;
|
||||
stagingRoot: string;
|
||||
cleanupToken: string;
|
||||
runnerTempIdentity: Readonly<{ dev: number; ino: number }>;
|
||||
stagingIdentity: Readonly<{ dev: number; ino: number }>;
|
||||
}>, dependencies: Readonly<{
|
||||
beforeRemove?: () => Promise<void>;
|
||||
}> = {}): Promise<void> {
|
||||
const parent = path.resolve(input.runnerTempRoot);
|
||||
const expected = path.join(parent, input.cleanupToken);
|
||||
if (
|
||||
!/^[A-Za-z0-9._-]+-[a-f0-9]{32}$/u.test(input.cleanupToken) ||
|
||||
path.resolve(input.stagingRoot) !== expected ||
|
||||
!Number.isSafeInteger(input.runnerTempIdentity.dev) ||
|
||||
input.runnerTempIdentity.dev <= 0 ||
|
||||
!Number.isSafeInteger(input.runnerTempIdentity.ino) ||
|
||||
input.runnerTempIdentity.ino <= 0
|
||||
|| !Number.isSafeInteger(input.stagingIdentity.dev)
|
||||
|| input.stagingIdentity.dev <= 0
|
||||
|| !Number.isSafeInteger(input.stagingIdentity.ino)
|
||||
|| input.stagingIdentity.ino <= 0
|
||||
) {
|
||||
throw new TypeError("promotion cleanup root/token mismatch");
|
||||
}
|
||||
const parentHandle = await open(
|
||||
parent,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
try {
|
||||
const openedParent = await parentHandle.stat();
|
||||
assertRunnerTempIdentity(openedParent, input.runnerTempIdentity);
|
||||
const descriptorRoot = `/proc/self/fd/${parentHandle.fd}`;
|
||||
const descriptorMetadata = await stat(descriptorRoot);
|
||||
if (!descriptorMetadata.isDirectory()) {
|
||||
throw new Error("descriptor-relative cleanup is unavailable");
|
||||
}
|
||||
const descriptorExpected = path.join(descriptorRoot, input.cleanupToken);
|
||||
let metadata;
|
||||
try {
|
||||
metadata = await lstat(descriptorExpected);
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return;
|
||||
throw error;
|
||||
}
|
||||
if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
|
||||
throw new TypeError("promotion cleanup leaf is unsafe");
|
||||
}
|
||||
assertStagingIdentity(metadata, input.stagingIdentity);
|
||||
const stagingHandle = await open(
|
||||
descriptorExpected,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
try {
|
||||
const stagingDescriptorRoot = `/proc/self/fd/${stagingHandle.fd}`;
|
||||
assertStagingIdentity(await stat(stagingDescriptorRoot), input.stagingIdentity);
|
||||
const names = (await readdir(stagingDescriptorRoot)).sort(asciiCompare);
|
||||
if (
|
||||
JSON.stringify(names) !==
|
||||
JSON.stringify([...PROMOTED_FILE_NAMES].sort(asciiCompare))
|
||||
) {
|
||||
throw new Error("promotion cleanup leaf does not contain the exact five files");
|
||||
}
|
||||
await dependencies.beforeRemove?.();
|
||||
const visibleParent = await lstat(parent);
|
||||
assertRunnerTempIdentity(visibleParent, input.runnerTempIdentity);
|
||||
// Re-bind the name to the inode before removing anything.
|
||||
//
|
||||
// The removals below run through the pinned staging descriptor, so they
|
||||
// always reach the owned inode even after the name has been re-pointed
|
||||
// somewhere else. That is safe for the substitute, but it destroys this
|
||||
// promotion's exact five first and only reports the substitution
|
||||
// afterwards — a caller that retries then finds a half-emptied staging
|
||||
// directory and no way to tell a completed cleanup from an interrupted
|
||||
// one. Detecting the swap here makes the failure total: nothing is
|
||||
// removed unless the leaf still is what was validated.
|
||||
assertStagingIdentity(await lstat(descriptorExpected), input.stagingIdentity);
|
||||
assertStagingIdentity(await stat(stagingDescriptorRoot), input.stagingIdentity);
|
||||
for (const name of PROMOTED_FILE_NAMES) {
|
||||
await rm(path.join(stagingDescriptorRoot, name), { force: false });
|
||||
}
|
||||
assertStagingIdentity(await stat(stagingDescriptorRoot), input.stagingIdentity);
|
||||
assertStagingIdentity(await lstat(descriptorExpected), input.stagingIdentity);
|
||||
await rmdir(descriptorExpected);
|
||||
} finally {
|
||||
await stagingHandle.close();
|
||||
}
|
||||
const afterParent = await lstat(parent);
|
||||
assertRunnerTempIdentity(afterParent, input.runnerTempIdentity);
|
||||
} finally {
|
||||
await parentHandle.close();
|
||||
}
|
||||
}
|
||||
|
||||
export async function publishPrivatePromotionStaging(
|
||||
runnerTempRoot: string,
|
||||
run: Readonly<{ id: string; attempt: number }>,
|
||||
files: readonly StagedFile[],
|
||||
randomBytes: (bytes: number) => Buffer,
|
||||
afterStagingWrite?: () => Promise<void>,
|
||||
afterFileWrite?: (name: PromotedFileName) => Promise<void>,
|
||||
sealStagedFiles?: (files: Readonly<Record<PromotedFileName, Buffer>>) => Promise<void>,
|
||||
afterMkdirBeforeOpen?: (stagingRoot: string) => Promise<void>,
|
||||
beforeSeal?: () => Promise<void>,
|
||||
): Promise<FinalizedPromotion> {
|
||||
if (
|
||||
JSON.stringify(files.map(({ name }) => name)) !==
|
||||
JSON.stringify(PROMOTED_FILE_NAMES) ||
|
||||
files.some(
|
||||
({ bytes, sha256: digest }) =>
|
||||
!Buffer.isBuffer(bytes) ||
|
||||
!/^[a-f0-9]{64}$/u.test(digest) ||
|
||||
sha256(bytes) !== digest,
|
||||
)
|
||||
) {
|
||||
throw new TypeError("private promotion staging requires the canonical exact-five bytes");
|
||||
}
|
||||
const parentPath = path.resolve(runnerTempRoot);
|
||||
const before = await lstat(parentPath);
|
||||
if (!before.isDirectory() || before.isSymbolicLink()) {
|
||||
throw new TypeError("runner temporary root must be a real directory");
|
||||
}
|
||||
const parentHandle = await open(
|
||||
parentPath,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
const tokenBytes = randomBytes(16);
|
||||
if (tokenBytes.byteLength !== 16) {
|
||||
await parentHandle.close();
|
||||
throw new TypeError("promotion staging nonce must contain exactly 128 random bits");
|
||||
}
|
||||
const safeRun = run.id.replaceAll(/[^A-Za-z0-9._-]/gu, "_").slice(0, 64) || "run";
|
||||
const cleanupToken = `promotion-${safeRun}-${run.attempt}-${tokenBytes.toString("hex")}`;
|
||||
const descriptorRoot = `/proc/self/fd/${parentHandle.fd}`;
|
||||
const descriptorStaging = path.join(descriptorRoot, cleanupToken);
|
||||
const visibleStaging = path.join(parentPath, cleanupToken);
|
||||
let ownsStaging = false;
|
||||
let stagingHandle: Awaited<ReturnType<typeof open>> | undefined;
|
||||
let createdStagingIdentity: Readonly<{ dev: number; ino: number }> | undefined;
|
||||
let stagingIdentity: Readonly<{ dev: number; ino: number }> | undefined;
|
||||
let openedIdentityVerified = false;
|
||||
const cleanup = async (primaryFailure?: unknown): Promise<void> => {
|
||||
const cleanupFailures: unknown[] = [];
|
||||
const attemptCleanup = async (operation: () => Promise<void>): Promise<void> => {
|
||||
try {
|
||||
await operation();
|
||||
} catch (error) {
|
||||
cleanupFailures.push(error);
|
||||
}
|
||||
};
|
||||
if (ownsStaging && openedIdentityVerified && stagingHandle && stagingIdentity) {
|
||||
const ownedIdentity = stagingIdentity;
|
||||
const stagingDescriptorRoot = `/proc/self/fd/${stagingHandle.fd}`;
|
||||
const removals = await Promise.allSettled(
|
||||
files.map(({ name }) => rm(path.join(stagingDescriptorRoot, name), { force: true })),
|
||||
);
|
||||
cleanupFailures.push(
|
||||
...removals.flatMap((result) =>
|
||||
result.status === "rejected" ? [result.reason] : [],
|
||||
),
|
||||
);
|
||||
await attemptCleanup(async () => {
|
||||
let visible;
|
||||
try {
|
||||
visible = await lstat(descriptorStaging);
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return;
|
||||
throw error;
|
||||
}
|
||||
if (
|
||||
visible.isDirectory() &&
|
||||
!visible.isSymbolicLink() &&
|
||||
visible.dev === ownedIdentity.dev &&
|
||||
visible.ino === ownedIdentity.ino
|
||||
) {
|
||||
await rmdir(descriptorStaging);
|
||||
}
|
||||
});
|
||||
}
|
||||
if (stagingHandle) {
|
||||
const ownedHandle = stagingHandle;
|
||||
await attemptCleanup(async () => ownedHandle.close());
|
||||
}
|
||||
await attemptCleanup(async () => parentHandle.close());
|
||||
if (cleanupFailures.length > 0) {
|
||||
throw new AggregateError(
|
||||
primaryFailure === undefined
|
||||
? cleanupFailures
|
||||
: [primaryFailure, ...cleanupFailures],
|
||||
primaryFailure instanceof Error
|
||||
? `${primaryFailure.message}; promotion staging cleanup also failed`
|
||||
: "promotion staging cleanup failed",
|
||||
{ cause: cleanupFailures.at(-1) },
|
||||
);
|
||||
}
|
||||
};
|
||||
let finalizedPromotion: FinalizedPromotion;
|
||||
try {
|
||||
const procMetadata = await stat(descriptorRoot);
|
||||
if (!procMetadata.isDirectory()) throw new Error("descriptor-relative staging is unavailable");
|
||||
makePrivateDirectory(descriptorStaging);
|
||||
ownsStaging = true;
|
||||
const createdStaging = await lstat(descriptorStaging);
|
||||
if (!createdStaging.isDirectory() || createdStaging.isSymbolicLink()) {
|
||||
throw new Error("created promotion staging leaf is unsafe");
|
||||
}
|
||||
createdStagingIdentity = Object.freeze({
|
||||
dev: createdStaging.dev,
|
||||
ino: createdStaging.ino,
|
||||
});
|
||||
await afterMkdirBeforeOpen?.(visibleStaging);
|
||||
const openedHandle = await open(
|
||||
descriptorStaging,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
let openedStaging;
|
||||
try {
|
||||
openedStaging = await openedHandle.stat();
|
||||
if (!openedStaging.isDirectory()) {
|
||||
throw new Error("promotion staging descriptor is not a directory");
|
||||
}
|
||||
if (
|
||||
openedStaging.dev !== createdStagingIdentity.dev ||
|
||||
openedStaging.ino !== createdStagingIdentity.ino
|
||||
) {
|
||||
throw new Error("promotion staging leaf identity changed between mkdir and open");
|
||||
}
|
||||
openedIdentityVerified = true;
|
||||
} catch (error) {
|
||||
try {
|
||||
await openedHandle.close();
|
||||
} catch (closeError) {
|
||||
throw new AggregateError(
|
||||
[error, closeError],
|
||||
error instanceof Error
|
||||
? `${error.message}; rejected staging descriptor close also failed`
|
||||
: "rejected staging descriptor and close both failed",
|
||||
{ cause: closeError },
|
||||
);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
stagingHandle = openedHandle;
|
||||
await stagingHandle.chmod(0o700);
|
||||
stagingIdentity = Object.freeze({ dev: openedStaging.dev, ino: openedStaging.ino });
|
||||
const stagingDescriptorRoot = `/proc/self/fd/${stagingHandle.fd}`;
|
||||
assertStagingIdentity(await stat(stagingDescriptorRoot), stagingIdentity);
|
||||
for (const file of files) {
|
||||
const handle = await open(
|
||||
path.join(stagingDescriptorRoot, file.name),
|
||||
constants.O_WRONLY |
|
||||
constants.O_CREAT |
|
||||
constants.O_EXCL |
|
||||
constants.O_NOFOLLOW,
|
||||
0o400,
|
||||
);
|
||||
try {
|
||||
await handle.chmod(0o400);
|
||||
await handle.writeFile(file.bytes);
|
||||
await handle.sync();
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
await afterFileWrite?.(file.name);
|
||||
}
|
||||
await syncHandle(stagingHandle);
|
||||
await syncHandle(parentHandle);
|
||||
await afterStagingWrite?.();
|
||||
await beforeSeal?.();
|
||||
const capturedFiles = await captureStagedFiles(stagingHandle, files);
|
||||
await sealStagedFiles?.(capturedFiles);
|
||||
const after = await lstat(parentPath);
|
||||
if (
|
||||
after.dev !== before.dev ||
|
||||
after.ino !== before.ino ||
|
||||
after.isSymbolicLink() ||
|
||||
!after.isDirectory()
|
||||
) {
|
||||
throw new Error("runner temporary parent identity changed during staging");
|
||||
}
|
||||
const visible = await lstat(visibleStaging);
|
||||
if (!visible.isDirectory() || visible.isSymbolicLink()) {
|
||||
throw new Error("promotion staging visibility identity mismatch");
|
||||
}
|
||||
assertStagingIdentity(visible, stagingIdentity);
|
||||
ownsStaging = false;
|
||||
finalizedPromotion = Object.freeze({
|
||||
stagingRoot: visibleStaging,
|
||||
cleanupToken,
|
||||
runnerTempIdentity: Object.freeze({ dev: before.dev, ino: before.ino }),
|
||||
stagingIdentity,
|
||||
files: Object.freeze(
|
||||
files.map(({ name, sha256: digest }) => Object.freeze({ name, sha256: digest })),
|
||||
),
|
||||
});
|
||||
} catch (error) {
|
||||
await cleanup(error);
|
||||
throw error;
|
||||
}
|
||||
await cleanup();
|
||||
return finalizedPromotion;
|
||||
}
|
||||
|
||||
async function captureStagedFiles(
|
||||
stagingHandle: Awaited<ReturnType<typeof open>>,
|
||||
declaredFiles: readonly StagedFile[],
|
||||
): Promise<Readonly<Record<PromotedFileName, Buffer>>> {
|
||||
const descriptorRoot = `/proc/self/fd/${stagingHandle.fd}`;
|
||||
const names = (await readdir(descriptorRoot)).sort(asciiCompare);
|
||||
if (
|
||||
JSON.stringify(names) !==
|
||||
JSON.stringify([...PROMOTED_FILE_NAMES].sort(asciiCompare))
|
||||
) {
|
||||
throw new Error("staged promotion seal requires exactly the canonical five files");
|
||||
}
|
||||
const declared = new Map(declaredFiles.map((file) => [file.name, file] as const));
|
||||
const captured = {} as Record<PromotedFileName, Buffer>;
|
||||
for (const name of PROMOTED_FILE_NAMES) {
|
||||
const expected = declared.get(name)!;
|
||||
const handle = await open(
|
||||
path.join(descriptorRoot, name),
|
||||
constants.O_RDONLY | constants.O_NOFOLLOW,
|
||||
);
|
||||
try {
|
||||
const before = await handle.stat();
|
||||
const maxBytes = name === "release-candidate.tar.gz" ? 268_435_456 : 16_777_216;
|
||||
if (
|
||||
!before.isFile() ||
|
||||
before.nlink !== 1 ||
|
||||
(before.mode & 0o777) !== 0o400 ||
|
||||
before.size <= 0 ||
|
||||
before.size > maxBytes
|
||||
) {
|
||||
throw new Error(
|
||||
`staged promotion file must be regular, single-link, bounded, and mode 0400: ${name}`,
|
||||
);
|
||||
}
|
||||
const bytes = await handle.readFile();
|
||||
const after = await handle.stat();
|
||||
if (
|
||||
after.dev !== before.dev ||
|
||||
after.ino !== before.ino ||
|
||||
after.size !== before.size ||
|
||||
after.nlink !== 1 ||
|
||||
(after.mode & 0o777) !== 0o400 ||
|
||||
bytes.byteLength !== before.size
|
||||
) {
|
||||
throw new Error(`staged promotion file inode or size changed during seal: ${name}`);
|
||||
}
|
||||
if (sha256(bytes) !== expected.sha256) {
|
||||
throw new Error(`staged promotion file digest mismatch during seal: ${name}`);
|
||||
}
|
||||
captured[name] = bytes;
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
}
|
||||
return Object.freeze(captured);
|
||||
}
|
||||
|
||||
function asciiCompare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
|
||||
function assertStagingIdentity(
|
||||
metadata: Readonly<{
|
||||
dev: number;
|
||||
ino: number;
|
||||
isDirectory: () => boolean;
|
||||
isSymbolicLink?: () => boolean;
|
||||
}>,
|
||||
expected: Readonly<{ dev: number; ino: number }>,
|
||||
): void {
|
||||
if (
|
||||
metadata.dev !== expected.dev ||
|
||||
metadata.ino !== expected.ino ||
|
||||
!metadata.isDirectory() ||
|
||||
metadata.isSymbolicLink?.()
|
||||
) {
|
||||
throw new Error("promotion staging leaf identity changed");
|
||||
}
|
||||
}
|
||||
|
||||
function assertRunnerTempIdentity(
|
||||
metadata: Readonly<{ dev: number; ino: number; isDirectory: () => boolean; isSymbolicLink?: () => boolean }>,
|
||||
expected: Readonly<{ dev: number; ino: number }>,
|
||||
): void {
|
||||
if (
|
||||
metadata.dev !== expected.dev ||
|
||||
metadata.ino !== expected.ino ||
|
||||
!metadata.isDirectory() ||
|
||||
metadata.isSymbolicLink?.()
|
||||
) {
|
||||
throw new Error("runner temporary parent identity changed during cleanup");
|
||||
}
|
||||
}
|
||||
|
||||
function capturedTrust(keyId: string, bytes: Buffer): ProviderTrust {
|
||||
const publicKey = createPublicKey(
|
||||
new TextDecoder("utf-8", { fatal: true }).decode(bytes),
|
||||
);
|
||||
return Object.freeze({
|
||||
keyId,
|
||||
publicKey,
|
||||
publicKeyFingerprint: providerPublicKeyFingerprint(publicKey),
|
||||
});
|
||||
}
|
||||
|
||||
async function capture(root: string, configuredPath: string, maxBytes: number): Promise<Buffer> {
|
||||
const absolute = path.resolve(root, configuredPath);
|
||||
const relative = path.relative(root, absolute);
|
||||
const outside =
|
||||
relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
|
||||
return readBoundedRegularFile({
|
||||
root: outside ? path.dirname(absolute) : root,
|
||||
relativePath: outside ? path.basename(absolute) : relative.replaceAll(path.sep, "/"),
|
||||
maxBytes,
|
||||
});
|
||||
}
|
||||
|
||||
function staged(name: PromotedFileName, bytes: Buffer): StagedFile {
|
||||
return Object.freeze({ name, bytes, sha256: sha256(bytes) });
|
||||
}
|
||||
|
||||
function canonicalJsonBytes(value: unknown): Buffer {
|
||||
return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
|
||||
}
|
||||
|
||||
function parseJson(bytes: Buffer): unknown {
|
||||
try {
|
||||
return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as unknown;
|
||||
} catch {
|
||||
throw new TypeError("captured provider evidence is not valid UTF-8 JSON");
|
||||
}
|
||||
}
|
||||
|
||||
function sha256(bytes: Buffer): string {
|
||||
return createHash("sha256").update(bytes).digest("hex");
|
||||
}
|
||||
|
||||
async function syncHandle(handle: Awaited<ReturnType<typeof open>>): Promise<void> {
|
||||
try {
|
||||
await handle.sync();
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "EINVAL") && !hasErrorCode(error, "ENOTSUP")) throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,209 @@
|
||||
export type ProviderKind = "vulnerability" | "provenance";
|
||||
|
||||
const MEMORY_MAX = 1_073_741_824;
|
||||
const TASKS_MAX = 64;
|
||||
const STOP_TIMEOUT_MS = 5_000;
|
||||
const RUNTIME_GRACE_MS = 10_000;
|
||||
const UNIT_NAME = /^ca-provider-(?:vulnerability|provenance)-[1-9][0-9]*-[0-9a-f]{24}\.scope$/u;
|
||||
const UNIT_NONCE = /^[0-9a-f]{24}$/u;
|
||||
const ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
|
||||
const ENFORCEMENT_GATE = [
|
||||
'cgroup_path=""',
|
||||
"while IFS=: read -r hierarchy controllers candidate; do",
|
||||
' if [ "$hierarchy" = 0 ] && [ -z "$controllers" ]; then cgroup_path=$candidate; fi',
|
||||
"done < /proc/self/cgroup",
|
||||
'if [ -z "$cgroup_path" ]; then',
|
||||
" printf '%s\\n' 'provider cgroup enforcement failed: unified cgroup v2 membership is required' >&2",
|
||||
" exit 125",
|
||||
"fi",
|
||||
'case "$cgroup_path" in',
|
||||
' */"$0") ;;',
|
||||
" *)",
|
||||
" printf '%s\\n' 'provider cgroup enforcement failed: unit membership is invalid' >&2",
|
||||
" exit 125",
|
||||
" ;;",
|
||||
"esac",
|
||||
"cgroup_root=/sys/fs/cgroup$cgroup_path",
|
||||
"require_cgroup_value() {",
|
||||
' actual=$(/bin/cat "$cgroup_root/$1") || {',
|
||||
" printf 'provider cgroup enforcement failed: cannot read %s\\n' \"$1\" >&2",
|
||||
" exit 125",
|
||||
" }",
|
||||
' if [ "$actual" != "$2" ]; then',
|
||||
" printf 'provider cgroup enforcement failed: %s is %s, expected %s\\n' \"$1\" \"$actual\" \"$2\" >&2",
|
||||
" exit 125",
|
||||
" fi",
|
||||
"}",
|
||||
`require_cgroup_value memory.max ${MEMORY_MAX}`,
|
||||
"require_cgroup_value memory.swap.max 0",
|
||||
`require_cgroup_value pids.max ${TASKS_MAX}`,
|
||||
"require_cgroup_value cpu.max '100000 100000'",
|
||||
'exec "$@"',
|
||||
].join("\n");
|
||||
|
||||
export function formatProviderCgroupUnitName(
|
||||
kind: ProviderKind,
|
||||
supervisorPid: number,
|
||||
nonce: string,
|
||||
): string {
|
||||
if (!Number.isSafeInteger(supervisorPid) || supervisorPid <= 0 || !UNIT_NONCE.test(nonce)) {
|
||||
throw new TypeError("provider cgroup unit identity is invalid");
|
||||
}
|
||||
const unit = `ca-provider-${kind}-${supervisorPid}-${nonce}.scope`;
|
||||
assertUnit(unit);
|
||||
return unit;
|
||||
}
|
||||
|
||||
export function systemdRunProviderArguments(
|
||||
unit: string,
|
||||
timeoutMs: number,
|
||||
cpuSeconds: number,
|
||||
nodeExecutable: string,
|
||||
wrapperScript: string,
|
||||
reportPath: string,
|
||||
reportDev: number,
|
||||
reportIno: number,
|
||||
): string[] {
|
||||
assertUnit(unit);
|
||||
if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > Number.MAX_SAFE_INTEGER - RUNTIME_GRACE_MS) {
|
||||
throw new TypeError("provider cgroup runtime is invalid");
|
||||
}
|
||||
if (!Number.isSafeInteger(cpuSeconds) || cpuSeconds <= 0) {
|
||||
throw new TypeError("provider cgroup CPU limit is invalid");
|
||||
}
|
||||
if (
|
||||
!nodeExecutable.startsWith("/") || !wrapperScript.startsWith("/") ||
|
||||
!reportPath.startsWith("/") || reportPath.includes("\0") ||
|
||||
!Number.isSafeInteger(reportDev) || reportDev <= 0 ||
|
||||
!Number.isSafeInteger(reportIno) || reportIno <= 0
|
||||
) {
|
||||
throw new TypeError("provider scope wrapper path is invalid");
|
||||
}
|
||||
return [
|
||||
"--user",
|
||||
"--scope",
|
||||
"--collect",
|
||||
"--quiet",
|
||||
"--expand-environment=no",
|
||||
`--unit=${unit}`,
|
||||
`--property=MemoryMax=${MEMORY_MAX}`,
|
||||
"--property=MemorySwapMax=0",
|
||||
`--property=TasksMax=${TASKS_MAX}`,
|
||||
"--property=CPUQuota=100%",
|
||||
"--property=CPUQuotaPeriodSec=100ms",
|
||||
"--property=KillMode=control-group",
|
||||
"--property=SendSIGKILL=yes",
|
||||
`--property=TimeoutStopSec=${STOP_TIMEOUT_MS}ms`,
|
||||
`--property=RuntimeMaxSec=${timeoutMs + RUNTIME_GRACE_MS}ms`,
|
||||
"--",
|
||||
"/bin/sh",
|
||||
"-eu",
|
||||
"-c",
|
||||
ENFORCEMENT_GATE,
|
||||
unit,
|
||||
nodeExecutable,
|
||||
wrapperScript,
|
||||
String(cpuSeconds),
|
||||
reportPath,
|
||||
String(reportDev),
|
||||
String(reportIno),
|
||||
];
|
||||
}
|
||||
|
||||
export type ProviderScopeFrame = Readonly<{
|
||||
bwrapInput: Buffer;
|
||||
/**
|
||||
* The sandboxed command, kept out of the args file on purpose.
|
||||
*
|
||||
* `bwrap --args FD` splices the file's options into the option stream, but
|
||||
* bubblewrap stops at the first non-option and never propagates the command
|
||||
* back out of the recursive parse. A command written into the args file is
|
||||
* therefore silently dropped and bubblewrap exits with its usage text, so
|
||||
* the sandbox is never entered and the provider produces no evidence at all.
|
||||
* Only the options may be hidden; the command travels on real argv.
|
||||
*
|
||||
* Nothing secret lives here: credentials and the provider command reach the
|
||||
* sandbox through `--setenv` inside the args file, and this vector only ever
|
||||
* names `prlimit` and a shell that expands `$PROVIDER_COMMAND`.
|
||||
*/
|
||||
bwrapCommand: readonly string[];
|
||||
reportPath: string;
|
||||
reportDev: number;
|
||||
reportIno: number;
|
||||
}>;
|
||||
|
||||
export function encodeProviderScopeFrame(input: ProviderScopeFrame): Buffer {
|
||||
if (
|
||||
!Buffer.isBuffer(input.bwrapInput) || input.bwrapInput.byteLength === 0 ||
|
||||
!input.reportPath.startsWith("/") || input.reportPath.includes("\0") ||
|
||||
!Number.isSafeInteger(input.reportDev) || input.reportDev <= 0 ||
|
||||
!Number.isSafeInteger(input.reportIno) || input.reportIno <= 0
|
||||
) {
|
||||
throw new TypeError("provider scope frame is invalid");
|
||||
}
|
||||
assertBwrapCommand(input.bwrapCommand);
|
||||
const payload = Buffer.from(JSON.stringify({
|
||||
bwrapInputBase64: input.bwrapInput.toString("base64"),
|
||||
bwrapCommand: [...input.bwrapCommand],
|
||||
reportPath: input.reportPath,
|
||||
reportDev: input.reportDev,
|
||||
reportIno: input.reportIno,
|
||||
}));
|
||||
const frame = Buffer.allocUnsafe(4 + payload.byteLength);
|
||||
frame.writeUInt32BE(payload.byteLength, 0);
|
||||
payload.copy(frame, 4);
|
||||
return frame;
|
||||
}
|
||||
|
||||
/**
|
||||
* The command vector bubblewrap will exec. It has to be an absolute executable
|
||||
* so the sandbox never resolves it through a `PATH` the caller controls.
|
||||
*/
|
||||
export function assertBwrapCommand(command: readonly string[]): void {
|
||||
if (
|
||||
!Array.isArray(command) || command.length === 0 ||
|
||||
typeof command[0] !== "string" || !command[0].startsWith("/") ||
|
||||
command.some((argument) =>
|
||||
typeof argument !== "string" || argument.includes("\0"),
|
||||
)
|
||||
) {
|
||||
throw new TypeError("provider bwrap command is invalid");
|
||||
}
|
||||
}
|
||||
|
||||
export function encodeProviderBwrapInput(
|
||||
optionArguments: readonly string[],
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
): Buffer {
|
||||
if (optionArguments.some((argument) => argument.includes("\0"))) {
|
||||
throw new TypeError("provider bwrap argument is invalid");
|
||||
}
|
||||
// A bare `--` ends bubblewrap's option stream. Inside an args file that also
|
||||
// ends the recursive parse, so everything after it is discarded rather than
|
||||
// executed. Refusing it here keeps the drop from being reintroduced by a
|
||||
// caller that appends a command to the option list.
|
||||
if (optionArguments.includes("--")) {
|
||||
throw new TypeError("provider bwrap options may not terminate the option stream");
|
||||
}
|
||||
const entries = Object.entries(environment).sort(([left], [right]) =>
|
||||
left < right ? -1 : left > right ? 1 : 0,
|
||||
);
|
||||
if (entries.some(([name, value]) =>
|
||||
!ENVIRONMENT_NAME.test(name) || value === undefined || value.includes("\0")
|
||||
)) {
|
||||
throw new TypeError("provider bwrap environment is invalid");
|
||||
}
|
||||
const input = ["--clearenv"];
|
||||
for (const [name, value] of entries) input.push("--setenv", name, value ?? "");
|
||||
input.push(...optionArguments);
|
||||
return Buffer.from(`${input.join("\0")}\0`);
|
||||
}
|
||||
|
||||
export function systemctlKillProviderArguments(unit: string): string[] {
|
||||
assertUnit(unit);
|
||||
return ["--user", "kill", "--kill-whom=all", "--signal=SIGKILL", unit];
|
||||
}
|
||||
|
||||
function assertUnit(unit: string): void {
|
||||
if (!UNIT_NAME.test(unit)) throw new TypeError("provider cgroup unit name is invalid");
|
||||
}
|
||||
@@ -0,0 +1,494 @@
|
||||
import { createHash, verify, type KeyObject } from "node:crypto";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
canonicalizeSupplyChainValue,
|
||||
PROJECT_NAME,
|
||||
supplyChainDigest,
|
||||
} from "./supply-chain.ts";
|
||||
|
||||
export const PROVIDER_FUTURE_SKEW_MS = 5 * 60 * 1_000;
|
||||
export const PROVIDER_MAX_LIFETIME_MS = 2 * 60 * 60 * 1_000;
|
||||
export const PROMOTION_VERIFIER_ID = `${PROJECT_NAME}/promotion-verifier`;
|
||||
export const PROMOTION_VERIFIER_VERSION = "3";
|
||||
|
||||
const sha256 = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const fingerprint = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
|
||||
const revision = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u);
|
||||
const nonce = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const nonEmptyString = z.string().min(1);
|
||||
const timestamp = z
|
||||
.string()
|
||||
.regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u)
|
||||
.refine((value) => new Date(value).toISOString() === value);
|
||||
const runSchema = z
|
||||
.object({ id: z.string().min(1).max(128), attempt: z.int().min(1).max(1_000) })
|
||||
.strict();
|
||||
const sourceSchema = z
|
||||
.object({ revision, sourceSetSha256: sha256 })
|
||||
.strict();
|
||||
const candidateSchema = z
|
||||
.object({
|
||||
archiveSha256: sha256,
|
||||
bundleSha256: sha256,
|
||||
distSha256: sha256,
|
||||
lockfileSha256: sha256,
|
||||
})
|
||||
.strict();
|
||||
const providerRunSchema = runSchema.extend({ invocationNonce: nonce }).strict();
|
||||
export const secretScanAttestationSchema = z
|
||||
.object({
|
||||
status: z.literal("PASS"),
|
||||
localEvidenceAssessmentSha256: sha256,
|
||||
sourceSetSha256: sha256,
|
||||
policySha256: sha256,
|
||||
sarifSha256: sha256,
|
||||
scanInputSha256: sha256,
|
||||
})
|
||||
.strict();
|
||||
const signatureSchema = z
|
||||
.object({
|
||||
algorithm: z.literal("Ed25519"),
|
||||
keyId: nonEmptyString,
|
||||
publicKeyFingerprint: fingerprint,
|
||||
value: z.string().regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u),
|
||||
})
|
||||
.strict();
|
||||
const providerCommon = {
|
||||
schemaVersion: z.literal(2),
|
||||
provider: nonEmptyString,
|
||||
issuedAt: timestamp,
|
||||
expiresAt: timestamp,
|
||||
run: providerRunSchema,
|
||||
source: sourceSchema,
|
||||
candidate: candidateSchema,
|
||||
signature: signatureSchema,
|
||||
} as const;
|
||||
|
||||
export const vulnerabilityProviderReportSchema = z
|
||||
.object({
|
||||
...providerCommon,
|
||||
evidenceType: z.literal("vulnerability-report"),
|
||||
secretScanAttestation: secretScanAttestationSchema,
|
||||
findings: z.array(z.record(z.string(), z.json())),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export const provenanceProviderAttestationSchema = z
|
||||
.object({
|
||||
...providerCommon,
|
||||
evidenceType: z.literal("provenance-attestation"),
|
||||
signer: nonEmptyString,
|
||||
subject: z
|
||||
.object({ name: z.literal("dist"), digest: z.object({ sha256 }).strict() })
|
||||
.strict(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const verificationCommon = {
|
||||
schemaVersion: z.literal(3),
|
||||
verifiedAt: timestamp,
|
||||
status: z.enum(["PASS", "FAIL_UNVERIFIED"]),
|
||||
verifier: z
|
||||
.object({ id: nonEmptyString, version: nonEmptyString })
|
||||
.strict(),
|
||||
run: runSchema,
|
||||
source: sourceSchema,
|
||||
candidate: candidateSchema,
|
||||
providerEvidence: z
|
||||
.object({
|
||||
vulnerabilityReportSha256: sha256,
|
||||
provenanceAttestationSha256: sha256,
|
||||
vulnerabilityInvocationNonce: nonce,
|
||||
provenanceInvocationNonce: nonce,
|
||||
vulnerabilityKeyId: nonEmptyString,
|
||||
vulnerabilityKeyFingerprint: fingerprint,
|
||||
provenanceKeyId: nonEmptyString,
|
||||
provenanceKeyFingerprint: fingerprint,
|
||||
secretScanAttestation: secretScanAttestationSchema,
|
||||
})
|
||||
.strict(),
|
||||
trustPolicySha256: sha256,
|
||||
failures: z.array(z.string()),
|
||||
} as const;
|
||||
|
||||
const providerVerificationV3Schema = z
|
||||
.object({
|
||||
...verificationCommon,
|
||||
artifactType: z.literal("provider-verification"),
|
||||
vulnerabilityStatus: z.enum(["PASS", "FAIL_UNVERIFIED"]),
|
||||
provenanceAttestationStatus: z.enum(["PASS", "FAIL_UNVERIFIED"]),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const promotionVerificationV3Schema = z
|
||||
.object({
|
||||
...verificationCommon,
|
||||
artifactType: z.literal("promotion-verification"),
|
||||
localEvidenceStatus: z.enum(["PASS", "FAIL"]),
|
||||
localEvidenceAssessmentSha256: sha256,
|
||||
providerVerificationSha256: sha256,
|
||||
})
|
||||
.strict();
|
||||
|
||||
export const providerVerificationArtifactSchema = z
|
||||
.discriminatedUnion("artifactType", [
|
||||
providerVerificationV3Schema,
|
||||
promotionVerificationV3Schema,
|
||||
])
|
||||
.superRefine((record, context) => {
|
||||
const subordinatePass =
|
||||
record.artifactType === "provider-verification"
|
||||
? record.vulnerabilityStatus === "PASS" &&
|
||||
record.provenanceAttestationStatus === "PASS"
|
||||
: record.localEvidenceStatus === "PASS";
|
||||
const coherentPass = subordinatePass && record.failures.length === 0;
|
||||
if ((record.status === "PASS") !== coherentPass) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["status"],
|
||||
message: "verification PASS must agree with subordinate statuses and failures",
|
||||
});
|
||||
}
|
||||
if (record.status === "FAIL_UNVERIFIED" && record.failures.length === 0) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["failures"],
|
||||
message: "failed verification requires a failure diagnostic",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
export type ProviderVerificationArtifactType = z.infer<
|
||||
typeof providerVerificationArtifactSchema
|
||||
>["artifactType"];
|
||||
|
||||
export type ProviderTrust = Readonly<{
|
||||
keyId: string;
|
||||
publicKey: KeyObject;
|
||||
publicKeyFingerprint: string;
|
||||
}>;
|
||||
|
||||
export type ExpectedPromotionContext = Readonly<{
|
||||
run: Readonly<{ id: string; attempt: number }>;
|
||||
source: Readonly<{ revision: string; sourceSetSha256: string }>;
|
||||
candidate: Readonly<{
|
||||
archiveSha256: string;
|
||||
bundleSha256: string;
|
||||
distSha256: string;
|
||||
lockfileSha256: string;
|
||||
}>;
|
||||
vulnerabilityInvocationNonce: string;
|
||||
provenanceInvocationNonce: string;
|
||||
secretScanAttestation: z.infer<typeof secretScanAttestationSchema>;
|
||||
}>;
|
||||
|
||||
export type PromotionEvidenceResult = Readonly<{
|
||||
status: "PASS" | "FAIL_UNVERIFIED";
|
||||
vulnerabilityStatus: "PASS" | "FAIL_UNVERIFIED";
|
||||
provenanceAttestationStatus: "PASS" | "FAIL_UNVERIFIED";
|
||||
failures: readonly string[];
|
||||
}>;
|
||||
|
||||
export function validateProviderEvidence(input: Readonly<{
|
||||
kind: "vulnerability" | "provenance";
|
||||
value: unknown;
|
||||
expected: ExpectedPromotionContext;
|
||||
trust: ProviderTrust | null;
|
||||
nowEpochMs?: () => number;
|
||||
}>): Readonly<{
|
||||
evidence: unknown | null;
|
||||
status: "PASS" | "FAIL_UNVERIFIED";
|
||||
failures: readonly string[];
|
||||
}> {
|
||||
const failures: string[] = [];
|
||||
const now = (input.nowEpochMs ?? Date.now)();
|
||||
if (input.kind === "vulnerability") {
|
||||
const parsed = vulnerabilityProviderReportSchema.safeParse(input.value);
|
||||
if (!parsed.success) {
|
||||
return Object.freeze({
|
||||
evidence: null,
|
||||
status: "FAIL_UNVERIFIED",
|
||||
failures: Object.freeze([
|
||||
"external vulnerability provider report is missing or invalid",
|
||||
]),
|
||||
});
|
||||
}
|
||||
validateCommonContext(
|
||||
"vulnerability report",
|
||||
parsed.data,
|
||||
input.expected,
|
||||
input.expected.vulnerabilityInvocationNonce,
|
||||
input.trust,
|
||||
now,
|
||||
failures,
|
||||
);
|
||||
if (
|
||||
JSON.stringify(parsed.data.secretScanAttestation) !==
|
||||
JSON.stringify(input.expected.secretScanAttestation)
|
||||
) {
|
||||
failures.push("vulnerability report secret scan attestation mismatch");
|
||||
}
|
||||
if (parsed.data.findings.length > 0) {
|
||||
failures.push("vulnerability report contains findings");
|
||||
}
|
||||
return Object.freeze({
|
||||
evidence: parsed.data,
|
||||
status: failures.length === 0 ? "PASS" : "FAIL_UNVERIFIED",
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
const parsed = provenanceProviderAttestationSchema.safeParse(input.value);
|
||||
if (!parsed.success) {
|
||||
return Object.freeze({
|
||||
evidence: null,
|
||||
status: "FAIL_UNVERIFIED",
|
||||
failures: Object.freeze([
|
||||
"external signed provenance attestation is missing or invalid",
|
||||
]),
|
||||
});
|
||||
}
|
||||
validateCommonContext(
|
||||
"provenance attestation",
|
||||
parsed.data,
|
||||
input.expected,
|
||||
input.expected.provenanceInvocationNonce,
|
||||
input.trust,
|
||||
now,
|
||||
failures,
|
||||
);
|
||||
if (parsed.data.subject.digest.sha256 !== input.expected.candidate.distSha256) {
|
||||
failures.push("provenance attestation subject dist digest mismatch");
|
||||
}
|
||||
return Object.freeze({
|
||||
evidence: parsed.data,
|
||||
status: failures.length === 0 ? "PASS" : "FAIL_UNVERIFIED",
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
|
||||
export function providerEvidenceSignaturePayload(value: unknown): Buffer {
|
||||
if (!isRecord(value)) return Buffer.from("null", "utf8");
|
||||
const { signature: _signature, ...payload } = value;
|
||||
return Buffer.from(JSON.stringify(canonicalizeSupplyChainValue(payload)), "utf8");
|
||||
}
|
||||
|
||||
export function providerPublicKeyFingerprint(publicKey: KeyObject): string {
|
||||
if (publicKey.asymmetricKeyType !== "ed25519") {
|
||||
throw new TypeError("provider trust key must be Ed25519");
|
||||
}
|
||||
return `sha256:${createHash("sha256")
|
||||
.update(publicKey.export({ type: "spki", format: "der" }))
|
||||
.digest("hex")}`;
|
||||
}
|
||||
|
||||
export function createTrustPolicy(input: Readonly<{
|
||||
vulnerabilityTrust: ProviderTrust;
|
||||
provenanceTrust: ProviderTrust;
|
||||
}>) {
|
||||
assertDistinctProviderTrust(input);
|
||||
return Object.freeze({
|
||||
algorithm: "Ed25519" as const,
|
||||
vulnerability: Object.freeze({
|
||||
keyId: input.vulnerabilityTrust.keyId,
|
||||
publicKeyFingerprint: input.vulnerabilityTrust.publicKeyFingerprint,
|
||||
}),
|
||||
provenance: Object.freeze({
|
||||
keyId: input.provenanceTrust.keyId,
|
||||
publicKeyFingerprint: input.provenanceTrust.publicKeyFingerprint,
|
||||
}),
|
||||
issuedAtFutureSkewMs: PROVIDER_FUTURE_SKEW_MS,
|
||||
maximumLifetimeMs: PROVIDER_MAX_LIFETIME_MS,
|
||||
});
|
||||
}
|
||||
|
||||
export function assertDistinctProviderTrust(input: Readonly<{
|
||||
vulnerabilityTrust: ProviderTrust;
|
||||
provenanceTrust: ProviderTrust;
|
||||
}>): void {
|
||||
const vulnerabilityFingerprint = providerPublicKeyFingerprint(
|
||||
input.vulnerabilityTrust.publicKey,
|
||||
);
|
||||
const provenanceFingerprint = providerPublicKeyFingerprint(
|
||||
input.provenanceTrust.publicKey,
|
||||
);
|
||||
if (
|
||||
input.vulnerabilityTrust.keyId === input.provenanceTrust.keyId ||
|
||||
vulnerabilityFingerprint === provenanceFingerprint ||
|
||||
input.vulnerabilityTrust.publicKeyFingerprint ===
|
||||
input.provenanceTrust.publicKeyFingerprint
|
||||
) {
|
||||
throw new TypeError("provider trust roles require distinct key identities and DER-SPKI fingerprints");
|
||||
}
|
||||
}
|
||||
|
||||
export function trustPolicySha256(input: Readonly<{
|
||||
vulnerabilityTrust: ProviderTrust;
|
||||
provenanceTrust: ProviderTrust;
|
||||
}>): string {
|
||||
return supplyChainDigest(createTrustPolicy(input));
|
||||
}
|
||||
|
||||
export function evaluatePromotionEvidence(input: Readonly<{
|
||||
expected: ExpectedPromotionContext;
|
||||
localStatus: unknown;
|
||||
vulnerabilityReport: unknown;
|
||||
provenanceAttestation: unknown;
|
||||
vulnerabilityTrust: ProviderTrust | null;
|
||||
provenanceTrust: ProviderTrust | null;
|
||||
nowEpochMs?: () => number;
|
||||
}>): PromotionEvidenceResult {
|
||||
const failures: string[] = [];
|
||||
if (input.localStatus !== "PASS") {
|
||||
failures.push("local supply-chain evidence is not PASS");
|
||||
}
|
||||
const now = (input.nowEpochMs ?? Date.now)();
|
||||
let vulnerabilityStatus: "PASS" | "FAIL_UNVERIFIED" = "FAIL_UNVERIFIED";
|
||||
let provenanceAttestationStatus: "PASS" | "FAIL_UNVERIFIED" = "FAIL_UNVERIFIED";
|
||||
|
||||
const vulnerability = vulnerabilityProviderReportSchema.safeParse(
|
||||
input.vulnerabilityReport,
|
||||
);
|
||||
if (!vulnerability.success) {
|
||||
failures.push("external vulnerability provider report is missing or invalid");
|
||||
} else {
|
||||
const before = failures.length;
|
||||
validateCommonContext(
|
||||
"vulnerability report",
|
||||
vulnerability.data,
|
||||
input.expected,
|
||||
input.expected.vulnerabilityInvocationNonce,
|
||||
input.vulnerabilityTrust,
|
||||
now,
|
||||
failures,
|
||||
);
|
||||
if (
|
||||
JSON.stringify(vulnerability.data.secretScanAttestation) !==
|
||||
JSON.stringify(input.expected.secretScanAttestation)
|
||||
) {
|
||||
failures.push("vulnerability report secret scan attestation mismatch");
|
||||
}
|
||||
if (vulnerability.data.findings.length > 0) {
|
||||
failures.push("vulnerability report contains findings");
|
||||
}
|
||||
if (failures.length === before && input.localStatus === "PASS") {
|
||||
vulnerabilityStatus = "PASS";
|
||||
}
|
||||
}
|
||||
|
||||
const provenance = provenanceProviderAttestationSchema.safeParse(
|
||||
input.provenanceAttestation,
|
||||
);
|
||||
if (!provenance.success) {
|
||||
failures.push("external signed provenance attestation is missing or invalid");
|
||||
} else {
|
||||
const before = failures.length;
|
||||
validateCommonContext(
|
||||
"provenance attestation",
|
||||
provenance.data,
|
||||
input.expected,
|
||||
input.expected.provenanceInvocationNonce,
|
||||
input.provenanceTrust,
|
||||
now,
|
||||
failures,
|
||||
);
|
||||
if (provenance.data.subject.digest.sha256 !== input.expected.candidate.distSha256) {
|
||||
failures.push("provenance attestation subject dist digest mismatch");
|
||||
}
|
||||
if (failures.length === before && input.localStatus === "PASS") {
|
||||
provenanceAttestationStatus = "PASS";
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
status:
|
||||
failures.length === 0 &&
|
||||
vulnerabilityStatus === "PASS" &&
|
||||
provenanceAttestationStatus === "PASS"
|
||||
? "PASS"
|
||||
: "FAIL_UNVERIFIED",
|
||||
vulnerabilityStatus,
|
||||
provenanceAttestationStatus,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
|
||||
function validateCommonContext(
|
||||
label: "vulnerability report" | "provenance attestation",
|
||||
evidence: z.infer<
|
||||
| typeof vulnerabilityProviderReportSchema
|
||||
| typeof provenanceProviderAttestationSchema
|
||||
>,
|
||||
expected: ExpectedPromotionContext,
|
||||
expectedNonce: string,
|
||||
trust: ProviderTrust | null,
|
||||
now: number,
|
||||
failures: string[],
|
||||
): void {
|
||||
if (
|
||||
evidence.run.id !== expected.run.id ||
|
||||
evidence.run.attempt !== expected.run.attempt
|
||||
) {
|
||||
failures.push(`${label} run identity mismatch`);
|
||||
}
|
||||
if (evidence.run.invocationNonce !== expectedNonce) {
|
||||
failures.push(`${label} invocation nonce mismatch`);
|
||||
}
|
||||
if (
|
||||
evidence.source.revision !== expected.source.revision ||
|
||||
evidence.source.sourceSetSha256 !== expected.source.sourceSetSha256
|
||||
) {
|
||||
failures.push(`${label} source identity mismatch`);
|
||||
}
|
||||
if (JSON.stringify(evidence.candidate) !== JSON.stringify(expected.candidate)) {
|
||||
failures.push(`${label} candidate identity mismatch`);
|
||||
}
|
||||
validateEvidenceTime(label, evidence.issuedAt, evidence.expiresAt, now, failures);
|
||||
if (
|
||||
!trust ||
|
||||
evidence.signature.keyId !== trust.keyId ||
|
||||
evidence.signature.publicKeyFingerprint !== trust.publicKeyFingerprint
|
||||
) {
|
||||
failures.push(`${label} trust identity mismatch`);
|
||||
return;
|
||||
}
|
||||
try {
|
||||
if (
|
||||
providerPublicKeyFingerprint(trust.publicKey) !== trust.publicKeyFingerprint ||
|
||||
!verify(
|
||||
null,
|
||||
providerEvidenceSignaturePayload(evidence),
|
||||
trust.publicKey,
|
||||
Buffer.from(evidence.signature.value, "base64"),
|
||||
)
|
||||
) {
|
||||
failures.push(`${label} signature verification failed`);
|
||||
}
|
||||
} catch {
|
||||
failures.push(`${label} signature verification failed`);
|
||||
}
|
||||
}
|
||||
|
||||
function validateEvidenceTime(
|
||||
label: string,
|
||||
issuedAt: string,
|
||||
expiresAt: string,
|
||||
now: number,
|
||||
failures: string[],
|
||||
): void {
|
||||
const issued = Date.parse(issuedAt);
|
||||
const expires = Date.parse(expiresAt);
|
||||
if (issued > now + PROVIDER_FUTURE_SKEW_MS) {
|
||||
failures.push(`${label} issuedAt exceeds allowed future skew`);
|
||||
}
|
||||
if (expires <= now) failures.push(`${label} is expired`);
|
||||
if (expires <= issued) failures.push(`${label} validity window is not positive`);
|
||||
if (expires - issued > PROVIDER_MAX_LIFETIME_MS) {
|
||||
failures.push(`${label} validity window exceeds two hours`);
|
||||
}
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
@@ -0,0 +1,763 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { createHash, randomBytes } from "node:crypto";
|
||||
import { constants } from "node:fs";
|
||||
import { lstat, open, type FileHandle } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
decodeProviderGuardianPublished,
|
||||
decodeProviderGuardianReady,
|
||||
encodeProviderGuardianCommit,
|
||||
encodeProviderGuardianGuard,
|
||||
encodeProviderGuardianPublish,
|
||||
MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES,
|
||||
MAX_PROVIDER_GUARDIAN_LEASE_MS,
|
||||
MAX_PROVIDER_SEALED_BYTES,
|
||||
providerGuardianRawStagingLeaf,
|
||||
providerGuardianSealedTempLeaf,
|
||||
type ProviderGuardianKind,
|
||||
} from "./provider-guardian-protocol.ts";
|
||||
import { cleanupOwnedProviderReport } from "./provider-raw-cleanup.ts";
|
||||
|
||||
const RESPONSE_TIMEOUT_MS = 5_000;
|
||||
const CLOSE_TIMEOUT_MS = 5_000;
|
||||
const MAX_CONTROL_OUTPUT_BYTES = 4_096;
|
||||
|
||||
type OwnedIdentity = Readonly<{ dev: number; ino: number }>;
|
||||
type RecoveryAuthority = Readonly<{
|
||||
rawDirectoryHandle: FileHandle;
|
||||
evidenceDirectoryHandle: FileHandle;
|
||||
rawStagingHandle: FileHandle;
|
||||
sealedTempHandle: FileHandle;
|
||||
rawIdentity: OwnedIdentity;
|
||||
sealedIdentity: OwnedIdentity;
|
||||
rawStagingPinnedPath: string;
|
||||
rawPinnedPath: string;
|
||||
sealedTempPinnedPath: string;
|
||||
sealedPinnedPath: string;
|
||||
}>;
|
||||
|
||||
export type ProviderGuardianLease = Readonly<{
|
||||
pid: number;
|
||||
rawPath: string;
|
||||
rawIdentity: OwnedIdentity;
|
||||
sealedPath: string;
|
||||
sealedTempPath: string;
|
||||
sealedIdentity: OwnedIdentity;
|
||||
prematureExit: Promise<Error>;
|
||||
publish(bytes: Buffer): Promise<void>;
|
||||
commit(): Promise<void>;
|
||||
abort(): Promise<void>;
|
||||
}>;
|
||||
|
||||
export type StartProviderGuardianInput = Readonly<{
|
||||
kind: ProviderGuardianKind;
|
||||
workspaceRoot: string;
|
||||
leaseMs: number;
|
||||
guardianScript: string;
|
||||
}>;
|
||||
|
||||
export type ProviderScopeGuardianLatch = Readonly<{
|
||||
activeFailure: Promise<Error>;
|
||||
close(): Promise<void>;
|
||||
failure(): Error | undefined;
|
||||
}>;
|
||||
|
||||
export function createProviderScopeGuardianLatch(
|
||||
guardianExit: Promise<Error>,
|
||||
): ProviderScopeGuardianLatch {
|
||||
let active = true;
|
||||
let closing: Promise<void> | undefined;
|
||||
let observedFailure: Error | undefined;
|
||||
let signalActiveFailure!: (error: Error) => void;
|
||||
const activeFailure = new Promise<Error>((resolve) => { signalActiveFailure = resolve; });
|
||||
void guardianExit.then((error) => {
|
||||
observedFailure = error;
|
||||
if (active) signalActiveFailure(error);
|
||||
});
|
||||
return Object.freeze({
|
||||
activeFailure,
|
||||
close: () => {
|
||||
closing ??= Promise.resolve().then(() => { active = false; });
|
||||
return closing;
|
||||
},
|
||||
failure: () => observedFailure,
|
||||
});
|
||||
}
|
||||
|
||||
export function assertProviderGuardianLeasePaths(
|
||||
lease: Readonly<{ rawPath: string; sealedPath: string }>,
|
||||
expected: Readonly<{ rawPath: string; sealedPath: string }>,
|
||||
): void {
|
||||
if (lease.rawPath !== expected.rawPath) {
|
||||
throw new Error("provider guardian returned a noncanonical raw path");
|
||||
}
|
||||
if (lease.sealedPath !== expected.sealedPath) {
|
||||
throw new Error("provider guardian returned a noncanonical sealed path");
|
||||
}
|
||||
}
|
||||
|
||||
type GuardianResult = Readonly<{
|
||||
code: number | null;
|
||||
error?: Error;
|
||||
signal: NodeJS.Signals | null;
|
||||
}>;
|
||||
|
||||
export async function startProviderGuardian(
|
||||
input: StartProviderGuardianInput,
|
||||
): Promise<ProviderGuardianLease> {
|
||||
if (
|
||||
(input.kind !== "vulnerability" && input.kind !== "provenance") ||
|
||||
!path.isAbsolute(input.workspaceRoot) || !path.isAbsolute(input.guardianScript) ||
|
||||
!Number.isSafeInteger(input.leaseMs) || input.leaseMs <= 0 ||
|
||||
input.leaseMs > MAX_PROVIDER_GUARDIAN_LEASE_MS
|
||||
) {
|
||||
throw new TypeError("provider guardian client input is invalid");
|
||||
}
|
||||
const rawLeaf = input.kind === "vulnerability"
|
||||
? "vulnerability-report.json"
|
||||
: "provenance-attestation.json";
|
||||
const evidenceRoot = path.resolve(input.workspaceRoot, "provider-evidence");
|
||||
const rawDirectory = path.join(evidenceRoot, "untrusted");
|
||||
const rawPath = path.join(evidenceRoot, "untrusted", rawLeaf);
|
||||
const sealedPath = path.join(evidenceRoot, rawLeaf);
|
||||
const nonce = randomBytes(32);
|
||||
const rawStagingLeaf = providerGuardianRawStagingLeaf(input.kind, nonce);
|
||||
const sealedTempLeaf = providerGuardianSealedTempLeaf(input.kind, nonce);
|
||||
const sealedTempPath = path.join(evidenceRoot, sealedTempLeaf);
|
||||
const recovery = await openRecoveryAuthority({
|
||||
rawDirectory,
|
||||
evidenceRoot,
|
||||
rawLeaf,
|
||||
rawStagingLeaf,
|
||||
sealedLeaf: rawLeaf,
|
||||
sealedTempLeaf,
|
||||
});
|
||||
let child: ReturnType<typeof spawn>;
|
||||
try {
|
||||
await assertRecoveryLeavesMissing(recovery);
|
||||
child = spawn(process.execPath, [input.guardianScript], {
|
||||
cwd: input.workspaceRoot,
|
||||
env: {},
|
||||
stdio: [
|
||||
"pipe",
|
||||
"pipe",
|
||||
"pipe",
|
||||
recovery.rawDirectoryHandle.fd,
|
||||
recovery.evidenceDirectoryHandle.fd,
|
||||
recovery.rawStagingHandle.fd,
|
||||
recovery.sealedTempHandle.fd,
|
||||
],
|
||||
});
|
||||
} catch (error) {
|
||||
return await closeRecoveryAndThrow(recovery, error);
|
||||
}
|
||||
if (!child.pid || !child.stdin || !child.stdout || !child.stderr) {
|
||||
child.kill("SIGKILL");
|
||||
return await closeRecoveryAndThrow(
|
||||
recovery,
|
||||
new Error("provider guardian process pipes are unavailable"),
|
||||
);
|
||||
}
|
||||
|
||||
let state: "starting" | "guarding" | "publishing" | "published" |
|
||||
"committing" | "aborting" | "terminated" = "starting";
|
||||
let stderr = Buffer.alloc(0);
|
||||
let inputError: Error | undefined;
|
||||
child.stdin.once("error", (error) => { inputError = error; });
|
||||
child.stderr.on("data", (chunk: Buffer | string) => {
|
||||
const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
|
||||
if (stderr.byteLength < MAX_CONTROL_OUTPUT_BYTES) {
|
||||
stderr = Buffer.concat([stderr, bytes.subarray(0, MAX_CONTROL_OUTPUT_BYTES - stderr.byteLength)]);
|
||||
}
|
||||
});
|
||||
const completion = guardianCompletion(child);
|
||||
let signalPrematureExit!: (error: Error) => void;
|
||||
const prematureExit = new Promise<Error>((resolve) => { signalPrematureExit = resolve; });
|
||||
void completion.then((result) => {
|
||||
if (state === "guarding" || state === "publishing" || state === "published") {
|
||||
signalPrematureExit(guardianCloseError(result, stderr));
|
||||
}
|
||||
});
|
||||
|
||||
let ready: ReturnType<typeof decodeProviderGuardianReady>;
|
||||
try {
|
||||
const readyResponse = waitForFrame(child.stdout, completion, "READY");
|
||||
child.stdin.write(encodeProviderGuardianGuard({
|
||||
kind: input.kind,
|
||||
nonce,
|
||||
deadlineEpochMs: Date.now() + input.leaseMs,
|
||||
}));
|
||||
ready = decodeProviderGuardianReady(await readyResponse, nonce);
|
||||
if (
|
||||
ready.sealedTempLeaf !== sealedTempLeaf ||
|
||||
ready.rawDev !== recovery.rawIdentity.dev ||
|
||||
ready.rawIno !== recovery.rawIdentity.ino ||
|
||||
ready.sealedDev !== recovery.sealedIdentity.dev ||
|
||||
ready.sealedIno !== recovery.sealedIdentity.ino
|
||||
) {
|
||||
throw new TypeError("provider guardian READY identity is invalid for its allocation");
|
||||
}
|
||||
await assertPinnedLeafIdentity(recovery.rawPinnedPath, {
|
||||
dev: ready.rawDev,
|
||||
ino: ready.rawIno,
|
||||
}, 0o600);
|
||||
await assertPinnedLeafIdentity(recovery.sealedTempPinnedPath, {
|
||||
dev: ready.sealedDev,
|
||||
ino: ready.sealedIno,
|
||||
}, 0o600);
|
||||
await assertPinnedLeafMissing(recovery.rawStagingPinnedPath);
|
||||
if (child.exitCode !== null || child.signalCode !== null) {
|
||||
throw guardianCloseError(await completion, stderr);
|
||||
}
|
||||
state = "guarding";
|
||||
} catch (error) {
|
||||
state = "aborting";
|
||||
child.stdin.end();
|
||||
const failures = [toError(error)];
|
||||
try {
|
||||
await waitForClose(completion, child);
|
||||
} catch (closeError) {
|
||||
failures.push(toError(closeError));
|
||||
}
|
||||
try {
|
||||
await cleanupStartupRecovery(recovery);
|
||||
} catch (cleanupError) {
|
||||
failures.push(toError(cleanupError));
|
||||
}
|
||||
try {
|
||||
await closeRecoveryAuthority(recovery);
|
||||
} catch (closeError) {
|
||||
failures.push(toError(closeError));
|
||||
}
|
||||
state = "terminated";
|
||||
if (failures.length > 1) {
|
||||
throw new AggregateError(failures, "provider guardian startup failed", { cause: error });
|
||||
}
|
||||
throw failures[0]!;
|
||||
}
|
||||
|
||||
const rawIdentity = Object.freeze({ dev: ready.rawDev, ino: ready.rawIno });
|
||||
const sealedIdentity = Object.freeze({ dev: ready.sealedDev, ino: ready.sealedIno });
|
||||
const fallback = Object.freeze({
|
||||
rawStagingPath: recovery.rawStagingPinnedPath,
|
||||
rawPath: recovery.rawPinnedPath,
|
||||
rawIdentity,
|
||||
sealedPath: recovery.sealedPinnedPath,
|
||||
sealedTempPath: recovery.sealedTempPinnedPath,
|
||||
sealedIdentity,
|
||||
});
|
||||
|
||||
const publish = async (bytes: Buffer): Promise<void> => {
|
||||
if (state !== "guarding") throw new Error("provider guardian lease is not ready to publish");
|
||||
if (!Buffer.isBuffer(bytes) || bytes.byteLength <= 0 || bytes.byteLength > MAX_PROVIDER_SEALED_BYTES) {
|
||||
throw new TypeError("provider guardian sealed bytes are invalid");
|
||||
}
|
||||
state = "publishing";
|
||||
try {
|
||||
await writePinnedSealedBytes(recovery.sealedTempHandle, sealedIdentity, bytes);
|
||||
const publishedResponse = waitForFrame(child.stdout!, completion, "PUBLISHED");
|
||||
child.stdin!.write(encodeProviderGuardianPublish({
|
||||
nonce,
|
||||
sealedDev: sealedIdentity.dev,
|
||||
sealedIno: sealedIdentity.ino,
|
||||
size: bytes.byteLength,
|
||||
sha256: createHash("sha256").update(bytes).digest("hex"),
|
||||
}));
|
||||
decodeProviderGuardianPublished(
|
||||
await publishedResponse,
|
||||
nonce,
|
||||
sealedIdentity,
|
||||
);
|
||||
if (inputError) throw inputError;
|
||||
state = "published";
|
||||
} catch (error) {
|
||||
state = "guarding";
|
||||
throw error;
|
||||
}
|
||||
};
|
||||
|
||||
const commit = async (): Promise<void> => {
|
||||
if (state !== "published") throw new Error("provider guardian lease is not ready to commit");
|
||||
state = "committing";
|
||||
child.stdin!.write(encodeProviderGuardianCommit(nonce));
|
||||
child.stdin!.end();
|
||||
let result: GuardianResult;
|
||||
try {
|
||||
result = await waitForClose(completion, child);
|
||||
} catch (error) {
|
||||
state = "terminated";
|
||||
return await cleanupFallbackCloseAndThrow(fallback, recovery, error);
|
||||
}
|
||||
state = "terminated";
|
||||
if (inputError) return await cleanupFallbackCloseAndThrow(fallback, recovery, inputError);
|
||||
if (result.error || result.code !== 0 || result.signal !== null) {
|
||||
return await cleanupFallbackCloseAndThrow(
|
||||
fallback,
|
||||
recovery,
|
||||
guardianCloseError(result, stderr),
|
||||
);
|
||||
}
|
||||
await closeRecoveryAuthority(recovery);
|
||||
};
|
||||
|
||||
const abort = async (): Promise<void> => {
|
||||
if (state !== "guarding" && state !== "published") {
|
||||
throw new Error("provider guardian lease already terminated");
|
||||
}
|
||||
state = "aborting";
|
||||
child.stdin!.end();
|
||||
let closeError: unknown;
|
||||
try {
|
||||
await waitForClose(completion, child);
|
||||
} catch (error) {
|
||||
closeError = error;
|
||||
}
|
||||
state = "terminated";
|
||||
if (closeError) return await cleanupFallbackCloseAndThrow(fallback, recovery, closeError);
|
||||
await cleanupFallbackAndClose(fallback, recovery);
|
||||
};
|
||||
|
||||
return Object.freeze({
|
||||
pid: child.pid,
|
||||
rawPath,
|
||||
rawIdentity,
|
||||
sealedPath,
|
||||
sealedTempPath,
|
||||
sealedIdentity,
|
||||
prematureExit,
|
||||
publish,
|
||||
commit,
|
||||
abort,
|
||||
});
|
||||
}
|
||||
|
||||
async function writePinnedSealedBytes(
|
||||
handle: FileHandle,
|
||||
identity: OwnedIdentity,
|
||||
bytes: Buffer,
|
||||
): Promise<void> {
|
||||
assertPinnedMetadata(await handle.stat(), identity, 0o600, 0);
|
||||
await handle.truncate(0);
|
||||
await handle.writeFile(bytes);
|
||||
await handle.chmod(0o400);
|
||||
await handle.sync();
|
||||
assertPinnedMetadata(await handle.stat(), identity, 0o400, bytes.byteLength);
|
||||
}
|
||||
|
||||
function assertPinnedMetadata(
|
||||
metadata: Awaited<ReturnType<Awaited<ReturnType<typeof open>>["stat"]>>,
|
||||
identity: OwnedIdentity,
|
||||
mode: number,
|
||||
size: number,
|
||||
): void {
|
||||
if (
|
||||
!metadata.isFile() || Number(metadata.dev) !== identity.dev ||
|
||||
Number(metadata.ino) !== identity.ino || Number(metadata.nlink) !== 1 ||
|
||||
(Number(metadata.mode) & 0o777) !== mode || Number(metadata.size) !== size
|
||||
) {
|
||||
throw new TypeError("provider guardian sealed temp identity changed");
|
||||
}
|
||||
}
|
||||
|
||||
function guardianCompletion(child: ReturnType<typeof spawn>): Promise<GuardianResult> {
|
||||
return new Promise((resolve) => {
|
||||
child.once("error", (error) => resolve({ code: null, error, signal: null }));
|
||||
child.once("close", (code, signal) => resolve({ code, signal }));
|
||||
});
|
||||
}
|
||||
|
||||
async function waitForFrame(
|
||||
stdout: NodeJS.ReadableStream,
|
||||
completion: Promise<GuardianResult>,
|
||||
label: string,
|
||||
): Promise<Buffer> {
|
||||
let timer: NodeJS.Timeout | undefined;
|
||||
let pending = Buffer.alloc(0);
|
||||
const response = new Promise<Buffer>((resolve, reject) => {
|
||||
const onData = (chunk: Buffer | string): void => {
|
||||
pending = Buffer.concat([pending, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
|
||||
if (pending.byteLength > MAX_CONTROL_OUTPUT_BYTES) {
|
||||
reject(new Error(`provider guardian ${label} output exceeded its bound`));
|
||||
return;
|
||||
}
|
||||
if (pending.byteLength < 4) return;
|
||||
const payloadBytes = pending.readUInt32BE(0);
|
||||
if (payloadBytes <= 0 || payloadBytes > MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES) {
|
||||
reject(new Error(`provider guardian ${label} frame length is invalid`));
|
||||
return;
|
||||
}
|
||||
if (pending.byteLength < payloadBytes + 4) return;
|
||||
if (pending.byteLength !== payloadBytes + 4) {
|
||||
reject(new Error(`provider guardian ${label} output has trailing bytes`));
|
||||
return;
|
||||
}
|
||||
resolve(pending.subarray(4));
|
||||
};
|
||||
stdout.on("data", onData);
|
||||
});
|
||||
try {
|
||||
return await Promise.race([
|
||||
response,
|
||||
completion.then((result) => { throw guardianCloseError(result, Buffer.alloc(0)); }),
|
||||
new Promise<never>((_resolve, reject) => {
|
||||
timer = setTimeout(
|
||||
() => reject(new Error(`provider guardian ${label} timed out`)),
|
||||
RESPONSE_TIMEOUT_MS,
|
||||
);
|
||||
}),
|
||||
]);
|
||||
} finally {
|
||||
if (timer) clearTimeout(timer);
|
||||
stdout.removeAllListeners("data");
|
||||
}
|
||||
}
|
||||
|
||||
async function waitForClose(
|
||||
completion: Promise<GuardianResult>,
|
||||
child: ReturnType<typeof spawn>,
|
||||
): Promise<GuardianResult> {
|
||||
let timer: NodeJS.Timeout | undefined;
|
||||
try {
|
||||
return await Promise.race([
|
||||
completion,
|
||||
new Promise<never>((_resolve, reject) => {
|
||||
timer = setTimeout(() => {
|
||||
child.kill("SIGKILL");
|
||||
reject(new Error("provider guardian did not close within its bound"));
|
||||
}, CLOSE_TIMEOUT_MS);
|
||||
}),
|
||||
]);
|
||||
} finally {
|
||||
if (timer) clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
|
||||
type FallbackIdentity = Readonly<{
|
||||
rawStagingPath: string;
|
||||
rawPath: string;
|
||||
rawIdentity: OwnedIdentity;
|
||||
sealedPath: string;
|
||||
sealedTempPath: string;
|
||||
sealedIdentity: OwnedIdentity;
|
||||
}>;
|
||||
|
||||
async function cleanupFallback(input: FallbackIdentity): Promise<void> {
|
||||
const failures: Error[] = [];
|
||||
for (const target of [
|
||||
{ path: input.rawStagingPath, identity: input.rawIdentity },
|
||||
{ path: input.rawPath, identity: input.rawIdentity },
|
||||
{ path: input.sealedTempPath, identity: input.sealedIdentity },
|
||||
{ path: input.sealedPath, identity: input.sealedIdentity },
|
||||
]) {
|
||||
try {
|
||||
await cleanupOwnedProviderReport({
|
||||
reportPath: target.path,
|
||||
reportDev: target.identity.dev,
|
||||
reportIno: target.identity.ino,
|
||||
});
|
||||
} catch (error) {
|
||||
failures.push(toError(error));
|
||||
}
|
||||
}
|
||||
if (failures.length > 0) {
|
||||
throw new AggregateError(failures, "provider guardian fallback cleanup failed", {
|
||||
cause: failures[0],
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function cleanupFallbackCloseAndThrow(
|
||||
fallback: FallbackIdentity,
|
||||
recovery: RecoveryAuthority,
|
||||
primaryError: unknown,
|
||||
): Promise<never> {
|
||||
const failures = [toError(primaryError)];
|
||||
try {
|
||||
await cleanupFallback(fallback);
|
||||
} catch (cleanupError) {
|
||||
failures.push(toError(cleanupError));
|
||||
}
|
||||
try {
|
||||
await closeRecoveryAuthority(recovery);
|
||||
} catch (closeError) {
|
||||
failures.push(toError(closeError));
|
||||
}
|
||||
if (failures.length > 1) {
|
||||
throw new AggregateError(failures, "provider guardian failure and recovery failed", {
|
||||
cause: failures[0],
|
||||
});
|
||||
}
|
||||
throw failures[0]!;
|
||||
}
|
||||
|
||||
async function cleanupFallbackAndClose(
|
||||
fallback: FallbackIdentity,
|
||||
recovery: RecoveryAuthority,
|
||||
): Promise<void> {
|
||||
const failures: Error[] = [];
|
||||
try {
|
||||
await cleanupFallback(fallback);
|
||||
} catch (cleanupError) {
|
||||
failures.push(toError(cleanupError));
|
||||
}
|
||||
try {
|
||||
await closeRecoveryAuthority(recovery);
|
||||
} catch (closeError) {
|
||||
failures.push(toError(closeError));
|
||||
}
|
||||
if (failures.length > 0) {
|
||||
throw new AggregateError(failures, "provider guardian abort recovery failed", {
|
||||
cause: failures[0],
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function openRecoveryAuthority(input: Readonly<{
|
||||
rawDirectory: string;
|
||||
evidenceRoot: string;
|
||||
rawLeaf: string;
|
||||
rawStagingLeaf: string;
|
||||
sealedLeaf: string;
|
||||
sealedTempLeaf: string;
|
||||
}>): Promise<RecoveryAuthority> {
|
||||
let rawDirectoryHandle: FileHandle | undefined;
|
||||
let evidenceDirectoryHandle: FileHandle | undefined;
|
||||
let rawStagingHandle: FileHandle | undefined;
|
||||
let sealedTempHandle: FileHandle | undefined;
|
||||
let rawIdentity: OwnedIdentity | undefined;
|
||||
let sealedIdentity: OwnedIdentity | undefined;
|
||||
let rawStagingPinnedPath: string | undefined;
|
||||
let rawPinnedPath: string | undefined;
|
||||
let sealedTempPinnedPath: string | undefined;
|
||||
let sealedPinnedPath: string | undefined;
|
||||
try {
|
||||
rawDirectoryHandle = await open(
|
||||
input.rawDirectory,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
await assertPinnedDirectory(rawDirectoryHandle, input.rawDirectory, "raw");
|
||||
evidenceDirectoryHandle = await open(
|
||||
input.evidenceRoot,
|
||||
constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
|
||||
);
|
||||
await assertPinnedDirectory(evidenceDirectoryHandle, input.evidenceRoot, "evidence");
|
||||
rawStagingPinnedPath =
|
||||
`/proc/self/fd/${rawDirectoryHandle.fd}/${input.rawStagingLeaf}`;
|
||||
rawPinnedPath = `/proc/self/fd/${rawDirectoryHandle.fd}/${input.rawLeaf}`;
|
||||
sealedTempPinnedPath =
|
||||
`/proc/self/fd/${evidenceDirectoryHandle.fd}/${input.sealedTempLeaf}`;
|
||||
sealedPinnedPath = `/proc/self/fd/${evidenceDirectoryHandle.fd}/${input.sealedLeaf}`;
|
||||
rawStagingHandle = await open(
|
||||
rawStagingPinnedPath,
|
||||
constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
const rawMetadata = await rawStagingHandle.stat();
|
||||
rawIdentity = Object.freeze({ dev: rawMetadata.dev, ino: rawMetadata.ino });
|
||||
assertAllocatedPrivateMetadata(rawMetadata, rawIdentity, "raw staging");
|
||||
await assertPinnedLeafIdentity(rawStagingPinnedPath, rawIdentity, 0o600);
|
||||
sealedTempHandle = await open(
|
||||
sealedTempPinnedPath,
|
||||
constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
const sealedMetadata = await sealedTempHandle.stat();
|
||||
sealedIdentity = Object.freeze({ dev: sealedMetadata.dev, ino: sealedMetadata.ino });
|
||||
assertAllocatedPrivateMetadata(sealedMetadata, sealedIdentity, "sealed temp");
|
||||
await assertPinnedLeafIdentity(sealedTempPinnedPath, sealedIdentity, 0o600);
|
||||
return Object.freeze({
|
||||
rawDirectoryHandle,
|
||||
evidenceDirectoryHandle,
|
||||
rawStagingHandle,
|
||||
sealedTempHandle,
|
||||
rawIdentity,
|
||||
sealedIdentity,
|
||||
rawStagingPinnedPath,
|
||||
rawPinnedPath,
|
||||
sealedTempPinnedPath,
|
||||
sealedPinnedPath,
|
||||
});
|
||||
} catch (error) {
|
||||
const failures = [toError(error)];
|
||||
for (const target of [
|
||||
{ path: rawStagingPinnedPath, identity: rawIdentity },
|
||||
{ path: rawPinnedPath, identity: rawIdentity },
|
||||
{ path: sealedTempPinnedPath, identity: sealedIdentity },
|
||||
{ path: sealedPinnedPath, identity: sealedIdentity },
|
||||
]) {
|
||||
if (!target.path || !target.identity) continue;
|
||||
try {
|
||||
await cleanupOwnedProviderReport({
|
||||
reportPath: target.path,
|
||||
reportDev: target.identity.dev,
|
||||
reportIno: target.identity.ino,
|
||||
});
|
||||
} catch (cleanupError) {
|
||||
failures.push(toError(cleanupError));
|
||||
}
|
||||
}
|
||||
for (const handle of [
|
||||
sealedTempHandle,
|
||||
rawStagingHandle,
|
||||
evidenceDirectoryHandle,
|
||||
rawDirectoryHandle,
|
||||
]) {
|
||||
if (!handle) continue;
|
||||
try { await handle.close(); } catch (closeError) { failures.push(toError(closeError)); }
|
||||
}
|
||||
if (failures.length > 1) {
|
||||
throw new AggregateError(failures, "provider guardian recovery setup failed", {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
throw failures[0]!;
|
||||
}
|
||||
}
|
||||
|
||||
function assertAllocatedPrivateMetadata(
|
||||
metadata: Awaited<ReturnType<FileHandle["stat"]>>,
|
||||
identity: OwnedIdentity,
|
||||
label: string,
|
||||
): void {
|
||||
if (
|
||||
!metadata.isFile() || Number(metadata.dev) !== identity.dev ||
|
||||
Number(metadata.ino) !== identity.ino || Number(metadata.nlink) !== 1 ||
|
||||
(Number(metadata.mode) & 0o777) !== 0o600 || Number(metadata.size) !== 0
|
||||
) {
|
||||
throw new TypeError(`provider guardian ${label} allocation is invalid`);
|
||||
}
|
||||
}
|
||||
|
||||
async function assertPinnedDirectory(
|
||||
handle: FileHandle,
|
||||
canonicalPath: string,
|
||||
label: string,
|
||||
): Promise<void> {
|
||||
const [descriptorMetadata, pathMetadata] = await Promise.all([
|
||||
handle.stat(),
|
||||
lstat(canonicalPath),
|
||||
]);
|
||||
if (
|
||||
!descriptorMetadata.isDirectory() || !pathMetadata.isDirectory() ||
|
||||
pathMetadata.isSymbolicLink() || descriptorMetadata.dev !== pathMetadata.dev ||
|
||||
descriptorMetadata.ino !== pathMetadata.ino
|
||||
) {
|
||||
throw new TypeError(`provider guardian ${label} recovery directory identity changed`);
|
||||
}
|
||||
}
|
||||
|
||||
async function assertRecoveryLeavesMissing(recovery: RecoveryAuthority): Promise<void> {
|
||||
await assertPinnedLeafMissing(recovery.rawPinnedPath);
|
||||
await assertPinnedLeafMissing(recovery.sealedPinnedPath);
|
||||
assertAllocatedPrivateMetadata(
|
||||
await recovery.rawStagingHandle.stat(),
|
||||
recovery.rawIdentity,
|
||||
"raw staging",
|
||||
);
|
||||
assertAllocatedPrivateMetadata(
|
||||
await recovery.sealedTempHandle.stat(),
|
||||
recovery.sealedIdentity,
|
||||
"sealed temp",
|
||||
);
|
||||
await assertPinnedLeafIdentity(
|
||||
recovery.rawStagingPinnedPath,
|
||||
recovery.rawIdentity,
|
||||
0o600,
|
||||
);
|
||||
await assertPinnedLeafIdentity(
|
||||
recovery.sealedTempPinnedPath,
|
||||
recovery.sealedIdentity,
|
||||
0o600,
|
||||
);
|
||||
}
|
||||
|
||||
async function assertPinnedLeafMissing(target: string): Promise<void> {
|
||||
try {
|
||||
await lstat(target);
|
||||
throw new Error("provider guardian transaction leaf already exists");
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function assertPinnedLeafIdentity(
|
||||
target: string,
|
||||
identity: OwnedIdentity,
|
||||
mode: number,
|
||||
): Promise<void> {
|
||||
const metadata = await lstat(target);
|
||||
if (
|
||||
!metadata.isFile() || metadata.isSymbolicLink() || metadata.dev !== identity.dev ||
|
||||
metadata.ino !== identity.ino || metadata.nlink !== 1 ||
|
||||
(metadata.mode & 0o777) !== mode || metadata.size !== 0
|
||||
) {
|
||||
throw new TypeError("provider guardian READY identity changed");
|
||||
}
|
||||
}
|
||||
|
||||
async function cleanupStartupRecovery(recovery: RecoveryAuthority): Promise<void> {
|
||||
await cleanupFallback({
|
||||
rawStagingPath: recovery.rawStagingPinnedPath,
|
||||
rawPath: recovery.rawPinnedPath,
|
||||
rawIdentity: recovery.rawIdentity,
|
||||
sealedTempPath: recovery.sealedTempPinnedPath,
|
||||
sealedPath: recovery.sealedPinnedPath,
|
||||
sealedIdentity: recovery.sealedIdentity,
|
||||
});
|
||||
}
|
||||
|
||||
async function closeRecoveryAuthority(recovery: RecoveryAuthority): Promise<void> {
|
||||
const failures: Error[] = [];
|
||||
for (const handle of [
|
||||
recovery.rawStagingHandle,
|
||||
recovery.sealedTempHandle,
|
||||
recovery.rawDirectoryHandle,
|
||||
recovery.evidenceDirectoryHandle,
|
||||
]) {
|
||||
try { await handle.close(); } catch (error) { failures.push(toError(error)); }
|
||||
}
|
||||
if (failures.length > 0) {
|
||||
throw new AggregateError(failures, "provider guardian recovery directory close failed", {
|
||||
cause: failures[0],
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function closeRecoveryAndThrow(
|
||||
recovery: RecoveryAuthority,
|
||||
primaryError: unknown,
|
||||
): Promise<never> {
|
||||
const failures = [toError(primaryError)];
|
||||
try {
|
||||
await cleanupStartupRecovery(recovery);
|
||||
} catch (cleanupError) {
|
||||
failures.push(toError(cleanupError));
|
||||
}
|
||||
try {
|
||||
await closeRecoveryAuthority(recovery);
|
||||
} catch (closeError) {
|
||||
failures.push(toError(closeError));
|
||||
}
|
||||
if (failures.length > 1) {
|
||||
throw new AggregateError(failures,
|
||||
"provider guardian failure and recovery close failed", { cause: failures[0] });
|
||||
}
|
||||
throw failures[0]!;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
|
||||
function guardianCloseError(result: GuardianResult, stderr: Buffer): Error {
|
||||
if (result.error) return result.error;
|
||||
const detail = stderr.toString("utf8").trim();
|
||||
return new Error(
|
||||
`provider guardian failed: exit=${result.code ?? "none"}, signal=${result.signal ?? "none"}${detail ? `, output=${detail}` : ""}`,
|
||||
);
|
||||
}
|
||||
|
||||
function toError(error: unknown): Error {
|
||||
return error instanceof Error ? error : new Error(String(error));
|
||||
}
|
||||
@@ -0,0 +1,396 @@
|
||||
import { timingSafeEqual } from "node:crypto";
|
||||
|
||||
export type ProviderGuardianKind = "vulnerability" | "provenance";
|
||||
|
||||
export const MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES = 4_092;
|
||||
export const MAX_PROVIDER_GUARDIAN_LEASE_MS = 40 * 60 * 1_000;
|
||||
export const MAX_PROVIDER_SEALED_BYTES = 8_388_608;
|
||||
const V2_GUARD_KEYS = ["type", "version", "kind", "nonce", "deadlineEpochMs"] as const;
|
||||
const READY_KEYS = [
|
||||
"type", "version", "nonce", "rawDev", "rawIno",
|
||||
"sealedTempLeaf", "sealedDev", "sealedIno",
|
||||
] as const;
|
||||
const PUBLISH_KEYS = [
|
||||
"type", "version", "nonce", "sealedDev", "sealedIno", "size", "sha256",
|
||||
] as const;
|
||||
const PUBLISHED_KEYS = ["type", "version", "nonce", "sealedDev", "sealedIno"] as const;
|
||||
const COMMIT_KEYS = ["type", "version", "nonce"] as const;
|
||||
|
||||
export type ProviderGuardianGuard = Readonly<{
|
||||
kind: ProviderGuardianKind;
|
||||
nonce: Buffer;
|
||||
deadlineEpochMs: number;
|
||||
}>;
|
||||
|
||||
export type ProviderGuardianReady = Readonly<{
|
||||
nonce: Buffer;
|
||||
rawDev: number;
|
||||
rawIno: number;
|
||||
sealedTempLeaf: string;
|
||||
sealedDev: number;
|
||||
sealedIno: number;
|
||||
}>;
|
||||
|
||||
export type ProviderGuardianPublish = Readonly<{
|
||||
nonce: Buffer;
|
||||
sealedDev: number;
|
||||
sealedIno: number;
|
||||
size: number;
|
||||
sha256: string;
|
||||
}>;
|
||||
|
||||
export type ProviderGuardianPublished = Readonly<{
|
||||
nonce: Buffer;
|
||||
sealedDev: number;
|
||||
sealedIno: number;
|
||||
}>;
|
||||
|
||||
export function providerGuardianSealedTempLeaf(
|
||||
kind: ProviderGuardianKind,
|
||||
nonce: Buffer,
|
||||
): string {
|
||||
const rawLeaf = baseLeaf(kind);
|
||||
assertV2Nonce(nonce);
|
||||
return `.${rawLeaf}.guardian-${nonce.subarray(0, 16).toString("hex")}.tmp`;
|
||||
}
|
||||
|
||||
export function providerGuardianRawStagingLeaf(
|
||||
kind: ProviderGuardianKind,
|
||||
nonce: Buffer,
|
||||
): string {
|
||||
const rawLeaf = baseLeaf(kind);
|
||||
assertV2Nonce(nonce);
|
||||
return `.${rawLeaf}.guardian-${nonce.subarray(0, 16).toString("hex")}.raw.tmp`;
|
||||
}
|
||||
|
||||
export function encodeProviderGuardianGuard(input: ProviderGuardianGuard): Buffer {
|
||||
assertV2Guard(input);
|
||||
return prefixFrame(encodeV2GuardPayload(input));
|
||||
}
|
||||
|
||||
export function decodeProviderGuardianGuard(
|
||||
payload: Buffer,
|
||||
options: Readonly<{ nowEpochMs: number; maxLeaseMs: number }>,
|
||||
): ProviderGuardianGuard {
|
||||
const value = parseRecord(payload, V2_GUARD_KEYS, "guard");
|
||||
const guard: ProviderGuardianGuard = {
|
||||
kind: value.kind as ProviderGuardianKind,
|
||||
nonce: parseV2Nonce(value.nonce),
|
||||
deadlineEpochMs: value.deadlineEpochMs as number,
|
||||
};
|
||||
if (value.type !== "guard" || value.version !== 2) {
|
||||
throw new TypeError("provider guardian guard version is invalid");
|
||||
}
|
||||
assertV2Guard(guard);
|
||||
if (
|
||||
!Number.isSafeInteger(options.nowEpochMs) ||
|
||||
!Number.isSafeInteger(options.maxLeaseMs) || options.maxLeaseMs <= 0 ||
|
||||
guard.deadlineEpochMs <= options.nowEpochMs ||
|
||||
guard.deadlineEpochMs > options.nowEpochMs + options.maxLeaseMs
|
||||
) {
|
||||
throw new TypeError("provider guardian guard deadline is invalid");
|
||||
}
|
||||
assertCanonical(payload, encodeV2GuardPayload(guard), "guard");
|
||||
return guard;
|
||||
}
|
||||
|
||||
export function encodeProviderGuardianReady(input: ProviderGuardianReady): Buffer {
|
||||
assertReady(input);
|
||||
return prefixFrame(encodeReadyPayload(input));
|
||||
}
|
||||
|
||||
export function decodeProviderGuardianReady(
|
||||
payload: Buffer,
|
||||
expectedNonce: Buffer,
|
||||
): ProviderGuardianReady {
|
||||
assertV2Nonce(expectedNonce);
|
||||
const value = parseRecord(payload, READY_KEYS, "READY");
|
||||
const ready: ProviderGuardianReady = {
|
||||
nonce: parseV2Nonce(value.nonce),
|
||||
rawDev: value.rawDev as number,
|
||||
rawIno: value.rawIno as number,
|
||||
sealedTempLeaf: value.sealedTempLeaf as string,
|
||||
sealedDev: value.sealedDev as number,
|
||||
sealedIno: value.sealedIno as number,
|
||||
};
|
||||
if (value.type !== "ready" || value.version !== 2) {
|
||||
throw new TypeError("provider guardian READY version is invalid");
|
||||
}
|
||||
assertReady(ready);
|
||||
assertAuthenticatedNonce(ready.nonce, expectedNonce, "READY");
|
||||
assertCanonical(payload, encodeReadyPayload(ready), "READY");
|
||||
return ready;
|
||||
}
|
||||
|
||||
export function encodeProviderGuardianPublish(input: ProviderGuardianPublish): Buffer {
|
||||
assertPublish(input);
|
||||
return prefixFrame(encodePublishPayload(input));
|
||||
}
|
||||
|
||||
export function decodeProviderGuardianPublish(
|
||||
payload: Buffer,
|
||||
expectedNonce: Buffer,
|
||||
): ProviderGuardianPublish {
|
||||
assertV2Nonce(expectedNonce);
|
||||
const value = parseRecord(payload, PUBLISH_KEYS, "publish");
|
||||
const publish: ProviderGuardianPublish = {
|
||||
nonce: parseV2Nonce(value.nonce),
|
||||
sealedDev: value.sealedDev as number,
|
||||
sealedIno: value.sealedIno as number,
|
||||
size: value.size as number,
|
||||
sha256: value.sha256 as string,
|
||||
};
|
||||
if (value.type !== "publish" || value.version !== 2) {
|
||||
throw new TypeError("provider guardian publish version is invalid");
|
||||
}
|
||||
assertPublish(publish);
|
||||
assertAuthenticatedNonce(publish.nonce, expectedNonce, "publish");
|
||||
assertCanonical(payload, encodePublishPayload(publish), "publish");
|
||||
return publish;
|
||||
}
|
||||
|
||||
export function encodeProviderGuardianPublished(input: ProviderGuardianPublished): Buffer {
|
||||
assertPublished(input);
|
||||
return prefixFrame(encodePublishedPayload(input));
|
||||
}
|
||||
|
||||
export function decodeProviderGuardianPublished(
|
||||
payload: Buffer,
|
||||
expectedNonce: Buffer,
|
||||
expectedIdentity: Readonly<{ dev: number; ino: number }>,
|
||||
): void {
|
||||
assertV2Nonce(expectedNonce);
|
||||
const value = parseRecord(payload, PUBLISHED_KEYS, "PUBLISHED");
|
||||
const published: ProviderGuardianPublished = {
|
||||
nonce: parseV2Nonce(value.nonce),
|
||||
sealedDev: value.sealedDev as number,
|
||||
sealedIno: value.sealedIno as number,
|
||||
};
|
||||
if (value.type !== "published" || value.version !== 2) {
|
||||
throw new TypeError("provider guardian PUBLISHED version is invalid");
|
||||
}
|
||||
assertPublished(published);
|
||||
assertAuthenticatedNonce(published.nonce, expectedNonce, "PUBLISHED");
|
||||
if (published.sealedDev !== expectedIdentity.dev || published.sealedIno !== expectedIdentity.ino) {
|
||||
throw new TypeError("provider guardian PUBLISHED identity is invalid");
|
||||
}
|
||||
assertCanonical(payload, encodePublishedPayload(published), "PUBLISHED");
|
||||
}
|
||||
|
||||
function encodeV2GuardPayload(input: ProviderGuardianGuard): Buffer {
|
||||
return Buffer.from(JSON.stringify({
|
||||
type: "guard",
|
||||
version: 2,
|
||||
kind: input.kind,
|
||||
nonce: input.nonce.toString("hex"),
|
||||
deadlineEpochMs: input.deadlineEpochMs,
|
||||
}));
|
||||
}
|
||||
|
||||
export function encodeProviderGuardianCommit(nonce: Buffer): Buffer {
|
||||
assertV2Nonce(nonce);
|
||||
return prefixFrame(encodeCommitPayload(nonce));
|
||||
}
|
||||
|
||||
export function decodeProviderGuardianCommit(payload: Buffer, expectedNonce: Buffer): void {
|
||||
assertPayloadSize(payload);
|
||||
assertV2Nonce(expectedNonce);
|
||||
const decoded = decodeUtf8(payload);
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(decoded);
|
||||
} catch {
|
||||
throw new TypeError("provider guardian commit JSON is invalid");
|
||||
}
|
||||
if (!isRecord(value) || !hasExactKeys(value, COMMIT_KEYS)) {
|
||||
throw new TypeError("provider guardian commit fields are invalid");
|
||||
}
|
||||
const nonce = parseV2Nonce(value.nonce);
|
||||
if (
|
||||
value.type !== "commit" || value.version !== 2 ||
|
||||
nonce.byteLength !== expectedNonce.byteLength ||
|
||||
!timingSafeEqual(nonce, expectedNonce)
|
||||
) {
|
||||
throw new TypeError("provider guardian commit authentication failed");
|
||||
}
|
||||
if (!payload.equals(encodeCommitPayload(nonce))) {
|
||||
throw new TypeError("provider guardian commit is not canonical");
|
||||
}
|
||||
}
|
||||
|
||||
function encodeCommitPayload(nonce: Buffer): Buffer {
|
||||
return Buffer.from(JSON.stringify({
|
||||
type: "commit",
|
||||
version: 2,
|
||||
nonce: nonce.toString("hex"),
|
||||
}));
|
||||
}
|
||||
|
||||
function encodeReadyPayload(input: ProviderGuardianReady): Buffer {
|
||||
return Buffer.from(JSON.stringify({
|
||||
type: "ready",
|
||||
version: 2,
|
||||
nonce: input.nonce.toString("hex"),
|
||||
rawDev: input.rawDev,
|
||||
rawIno: input.rawIno,
|
||||
sealedTempLeaf: input.sealedTempLeaf,
|
||||
sealedDev: input.sealedDev,
|
||||
sealedIno: input.sealedIno,
|
||||
}));
|
||||
}
|
||||
|
||||
function encodePublishPayload(input: ProviderGuardianPublish): Buffer {
|
||||
return Buffer.from(JSON.stringify({
|
||||
type: "publish",
|
||||
version: 2,
|
||||
nonce: input.nonce.toString("hex"),
|
||||
sealedDev: input.sealedDev,
|
||||
sealedIno: input.sealedIno,
|
||||
size: input.size,
|
||||
sha256: input.sha256,
|
||||
}));
|
||||
}
|
||||
|
||||
function encodePublishedPayload(input: ProviderGuardianPublished): Buffer {
|
||||
return Buffer.from(JSON.stringify({
|
||||
type: "published",
|
||||
version: 2,
|
||||
nonce: input.nonce.toString("hex"),
|
||||
sealedDev: input.sealedDev,
|
||||
sealedIno: input.sealedIno,
|
||||
}));
|
||||
}
|
||||
|
||||
function prefixFrame(payload: Buffer): Buffer {
|
||||
if (payload.byteLength <= 0 || payload.byteLength > MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES) {
|
||||
throw new TypeError("provider guardian frame size is invalid");
|
||||
}
|
||||
const frame = Buffer.allocUnsafe(payload.byteLength + 4);
|
||||
frame.writeUInt32BE(payload.byteLength, 0);
|
||||
payload.copy(frame, 4);
|
||||
return frame;
|
||||
}
|
||||
|
||||
function assertV2Guard(input: ProviderGuardianGuard): void {
|
||||
if (
|
||||
(input.kind !== "vulnerability" && input.kind !== "provenance") ||
|
||||
!isV2Nonce(input.nonce) ||
|
||||
!Number.isSafeInteger(input.deadlineEpochMs) || input.deadlineEpochMs <= 0
|
||||
) {
|
||||
throw new TypeError("provider guardian guard fields are invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function baseLeaf(kind: ProviderGuardianKind): string {
|
||||
if (kind === "vulnerability") return "vulnerability-report.json";
|
||||
if (kind === "provenance") return "provenance-attestation.json";
|
||||
throw new TypeError("provider guardian kind is invalid");
|
||||
}
|
||||
|
||||
function assertReady(input: ProviderGuardianReady): void {
|
||||
if (
|
||||
!isV2Nonce(input.nonce) ||
|
||||
!isIdentityPart(input.rawDev) || !isIdentityPart(input.rawIno) ||
|
||||
typeof input.sealedTempLeaf !== "string" ||
|
||||
!/^\.(?:vulnerability-report|provenance-attestation)\.json\.guardian-[0-9a-f]{32}\.tmp$/u
|
||||
.test(input.sealedTempLeaf) ||
|
||||
!isIdentityPart(input.sealedDev) || !isIdentityPart(input.sealedIno)
|
||||
) {
|
||||
throw new TypeError("provider guardian READY fields are invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function assertPublish(input: ProviderGuardianPublish): void {
|
||||
if (
|
||||
!isV2Nonce(input.nonce) ||
|
||||
!isIdentityPart(input.sealedDev) || !isIdentityPart(input.sealedIno) ||
|
||||
!Number.isSafeInteger(input.size) || input.size <= 0 || input.size > MAX_PROVIDER_SEALED_BYTES ||
|
||||
typeof input.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(input.sha256)
|
||||
) {
|
||||
throw new TypeError("provider guardian publish fields are invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function assertPublished(input: ProviderGuardianPublished): void {
|
||||
if (
|
||||
!isV2Nonce(input.nonce) ||
|
||||
!isIdentityPart(input.sealedDev) || !isIdentityPart(input.sealedIno)
|
||||
) {
|
||||
throw new TypeError("provider guardian PUBLISHED fields are invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function assertV2Nonce(nonce: Buffer): void {
|
||||
if (!isV2Nonce(nonce)) throw new TypeError("provider guardian nonce is invalid");
|
||||
}
|
||||
|
||||
function isV2Nonce(nonce: Buffer): boolean {
|
||||
return Buffer.isBuffer(nonce) && nonce.byteLength === 32;
|
||||
}
|
||||
|
||||
function parseV2Nonce(value: unknown): Buffer {
|
||||
return typeof value === "string" && /^[0-9a-f]{64}$/u.test(value)
|
||||
? Buffer.from(value, "hex")
|
||||
: Buffer.alloc(0);
|
||||
}
|
||||
|
||||
function isIdentityPart(value: unknown): value is number {
|
||||
return Number.isSafeInteger(value) && (value as number) > 0;
|
||||
}
|
||||
|
||||
function assertAuthenticatedNonce(received: Buffer, expected: Buffer, label: string): void {
|
||||
if (received.byteLength !== expected.byteLength || !timingSafeEqual(received, expected)) {
|
||||
throw new TypeError(`provider guardian ${label} authentication failed`);
|
||||
}
|
||||
}
|
||||
|
||||
function parseRecord(
|
||||
payload: Buffer,
|
||||
expectedKeys: readonly string[],
|
||||
label: string,
|
||||
): Record<string, unknown> {
|
||||
assertPayloadSize(payload);
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(decodeUtf8(payload));
|
||||
} catch (error) {
|
||||
if (error instanceof TypeError && /provider guardian/u.test(error.message)) throw error;
|
||||
throw new TypeError(`provider guardian ${label} JSON is invalid`, { cause: error });
|
||||
}
|
||||
if (!isRecord(value) || !hasExactKeys(value, expectedKeys)) {
|
||||
throw new TypeError(`provider guardian ${label} fields are invalid`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function assertCanonical(payload: Buffer, canonical: Buffer, label: string): void {
|
||||
if (!payload.equals(canonical)) {
|
||||
throw new TypeError(`provider guardian ${label} frame is not canonical`);
|
||||
}
|
||||
}
|
||||
|
||||
function assertPayloadSize(payload: Buffer): void {
|
||||
if (!Buffer.isBuffer(payload) || payload.byteLength <= 0 || payload.byteLength > MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES) {
|
||||
throw new TypeError("provider guardian frame size is invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function decodeUtf8(payload: Buffer): string {
|
||||
let decoded: string;
|
||||
try {
|
||||
decoded = new TextDecoder("utf-8", { fatal: true }).decode(payload);
|
||||
} catch {
|
||||
throw new TypeError("provider guardian frame UTF-8 is invalid");
|
||||
}
|
||||
if (decoded.includes("\0")) throw new TypeError("provider guardian frame contains NUL");
|
||||
return decoded;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value && typeof value === "object" && !Array.isArray(value));
|
||||
}
|
||||
|
||||
function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
|
||||
const keys = Object.keys(value);
|
||||
return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
export type ProviderOutputLimiter = Readonly<{
|
||||
consume(chunk: Buffer | string): void;
|
||||
bytes(): number;
|
||||
}>;
|
||||
|
||||
export function createProviderOutputLimiter(
|
||||
maxBytes: number,
|
||||
onExceeded: () => void,
|
||||
): ProviderOutputLimiter {
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || typeof onExceeded !== "function") {
|
||||
throw new TypeError("provider output limiter input is invalid");
|
||||
}
|
||||
let observedBytes = 0;
|
||||
let exceeded = false;
|
||||
return Object.freeze({
|
||||
consume: (chunk: Buffer | string) => {
|
||||
if (exceeded) return;
|
||||
const bytes = Buffer.isBuffer(chunk) ? chunk.byteLength : Buffer.byteLength(chunk);
|
||||
observedBytes += bytes;
|
||||
if (observedBytes > maxBytes) {
|
||||
exceeded = true;
|
||||
onExceeded();
|
||||
}
|
||||
},
|
||||
bytes: () => observedBytes,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,103 @@
|
||||
import { spawn, type ChildProcess } from "node:child_process";
|
||||
|
||||
export type ProviderProcessInput = Readonly<{
|
||||
executable: string;
|
||||
arguments: readonly string[];
|
||||
environment: NodeJS.ProcessEnv;
|
||||
timeoutMs: number;
|
||||
}>;
|
||||
|
||||
type ProviderChild = Pick<ChildProcess, "kill" | "once" | "pid">;
|
||||
|
||||
export async function runProviderProcess(
|
||||
input: ProviderProcessInput,
|
||||
dependencies: Readonly<{
|
||||
spawnChild?: (input: ProviderProcessInput) => ProviderChild;
|
||||
setTimer?: (callback: () => void, milliseconds: number) => ReturnType<typeof setTimeout>;
|
||||
clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
|
||||
killProcessGroup?: (child: ProviderChild) => void;
|
||||
}> = {},
|
||||
): Promise<void> {
|
||||
if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs <= 0) {
|
||||
throw new TypeError("provider process timeout must be a positive integer");
|
||||
}
|
||||
const child = (dependencies.spawnChild ?? defaultSpawn)(input);
|
||||
const setTimer = dependencies.setTimer ?? setTimeout;
|
||||
const clearTimer = dependencies.clearTimer ?? clearTimeout;
|
||||
const killProcessGroup = dependencies.killProcessGroup ?? defaultKillProcessGroup;
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
let settled = false;
|
||||
let timedOut = false;
|
||||
const killFailures: unknown[] = [];
|
||||
const settle = (error?: Error): void => {
|
||||
if (settled) return;
|
||||
settled = true;
|
||||
clearTimer(timer);
|
||||
error ? reject(error) : resolve();
|
||||
};
|
||||
const timer = setTimer(() => {
|
||||
timedOut = true;
|
||||
try {
|
||||
killProcessGroup(child);
|
||||
} catch (groupError) {
|
||||
killFailures.push(groupError);
|
||||
try {
|
||||
child.kill("SIGKILL");
|
||||
} catch (fallbackError) {
|
||||
killFailures.push(fallbackError);
|
||||
}
|
||||
}
|
||||
}, input.timeoutMs);
|
||||
child.once("error", (error: Error) => {
|
||||
if (!timedOut) settle(error);
|
||||
});
|
||||
child.once("close", (code: number | null, signal: NodeJS.Signals | null) => {
|
||||
if (timedOut) {
|
||||
const timeoutError = new Error(
|
||||
"sandboxed external provider command timed out after process close",
|
||||
);
|
||||
settle(
|
||||
killFailures.length === 0
|
||||
? timeoutError
|
||||
: new AggregateError(
|
||||
[timeoutError, ...killFailures],
|
||||
"sandboxed external provider timed out and process-group kill failed before close",
|
||||
{ cause: killFailures.at(-1) },
|
||||
),
|
||||
);
|
||||
} else if (code === 0 && signal === null) {
|
||||
settle();
|
||||
} else {
|
||||
settle(
|
||||
new Error(
|
||||
`sandboxed external provider failed: exit=${code ?? "none"}, signal=${signal ?? "none"}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function defaultSpawn(input: ProviderProcessInput): ProviderChild {
|
||||
return spawn(input.executable, [...input.arguments], {
|
||||
env: input.environment,
|
||||
stdio: "inherit",
|
||||
detached: true,
|
||||
});
|
||||
}
|
||||
|
||||
function defaultKillProcessGroup(child: ProviderChild): void {
|
||||
if (child.pid && child.pid > 0) {
|
||||
try {
|
||||
process.kill(-child.pid, "SIGKILL");
|
||||
return;
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ESRCH")) throw error;
|
||||
}
|
||||
}
|
||||
child.kill("SIGKILL");
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { lstat, rename, unlink } from "node:fs/promises";
|
||||
|
||||
export type ProviderRawIdentity = Readonly<{
|
||||
reportPath: string;
|
||||
reportDev: number;
|
||||
reportIno: number;
|
||||
}>;
|
||||
|
||||
export async function cleanupOwnedProviderReport(
|
||||
identity: ProviderRawIdentity,
|
||||
): Promise<boolean> {
|
||||
try {
|
||||
const metadata = await lstat(identity.reportPath);
|
||||
if (!matchesReportIdentity(metadata, identity)) return false;
|
||||
const quarantine = `${identity.reportPath}.parent-loss-${process.pid}-${randomBytes(16).toString("hex")}`;
|
||||
await rename(identity.reportPath, quarantine);
|
||||
const quarantinedMetadata = await lstat(quarantine);
|
||||
if (!matchesReportIdentity(quarantinedMetadata, identity)) {
|
||||
throw new Error("provider raw output identity changed during parent-loss cleanup");
|
||||
}
|
||||
await unlink(quarantine);
|
||||
return true;
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return false;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function matchesReportIdentity(
|
||||
metadata: Awaited<ReturnType<typeof lstat>>,
|
||||
identity: ProviderRawIdentity,
|
||||
): boolean {
|
||||
return metadata.isFile() && !metadata.isSymbolicLink() &&
|
||||
metadata.dev === identity.reportDev && metadata.ino === identity.reportIno;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,641 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
closeSync,
|
||||
fstatSync,
|
||||
fsyncSync,
|
||||
lstatSync,
|
||||
readlinkSync,
|
||||
readSync,
|
||||
type Stats,
|
||||
writeSync,
|
||||
createReadStream,
|
||||
} from "node:fs";
|
||||
import { link, lstat, unlink } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
decodeProviderGuardianCommit,
|
||||
decodeProviderGuardianGuard,
|
||||
decodeProviderGuardianPublish,
|
||||
encodeProviderGuardianPublished,
|
||||
encodeProviderGuardianReady,
|
||||
MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES,
|
||||
MAX_PROVIDER_GUARDIAN_LEASE_MS,
|
||||
providerGuardianRawStagingLeaf,
|
||||
providerGuardianSealedTempLeaf,
|
||||
type ProviderGuardianGuard,
|
||||
type ProviderGuardianKind,
|
||||
} from "./provider-guardian-protocol.ts";
|
||||
import { cleanupOwnedProviderReport } from "./provider-raw-cleanup.ts";
|
||||
|
||||
type OwnedIdentity = Readonly<{ dev: number; ino: number }>;
|
||||
type BootstrapAuthority = Readonly<{
|
||||
kind: ProviderGuardianKind;
|
||||
noncePrefix: string;
|
||||
rawStagingLeaf: string;
|
||||
rawStagingPath: string;
|
||||
rawPath: string;
|
||||
rawIdentity: OwnedIdentity;
|
||||
sealedTempLeaf: string;
|
||||
sealedTempPath: string;
|
||||
sealedPath: string;
|
||||
sealedIdentity: OwnedIdentity;
|
||||
}>;
|
||||
type BoundPrivateAuthority = Readonly<{
|
||||
identity: OwnedIdentity;
|
||||
leaf: string;
|
||||
noncePrefix: string;
|
||||
path: string;
|
||||
stem: string;
|
||||
}>;
|
||||
type GuardianTransaction = Readonly<{ guard: ProviderGuardianGuard }>;
|
||||
|
||||
const RAW_DIRECTORY_FD = 3;
|
||||
const EVIDENCE_DIRECTORY_FD = 4;
|
||||
const RAW_STAGING_FD = 5;
|
||||
const SEALED_TEMP_FD = 6;
|
||||
const RAW_DIRECTORY_PATH = `/proc/self/fd/${RAW_DIRECTORY_FD}`;
|
||||
const EVIDENCE_DIRECTORY_PATH = `/proc/self/fd/${EVIDENCE_DIRECTORY_FD}`;
|
||||
const RAW_STAGING_FD_PATH = `/proc/self/fd/${RAW_STAGING_FD}`;
|
||||
const SEALED_TEMP_FD_PATH = `/proc/self/fd/${SEALED_TEMP_FD}`;
|
||||
const RAW_STAGING_PATTERN =
|
||||
/^\.(vulnerability-report|provenance-attestation)\.json\.guardian-([0-9a-f]{32})\.raw\.tmp$/u;
|
||||
const SEALED_TEMP_PATTERN =
|
||||
/^\.(vulnerability-report|provenance-attestation)\.json\.guardian-([0-9a-f]{32})\.tmp$/u;
|
||||
|
||||
let privateFdsClosed = false;
|
||||
const bootstrap = await initializeBootstrap();
|
||||
let pending = Buffer.alloc(0);
|
||||
let expectedBytes: number | undefined;
|
||||
let state: "starting" | "guarding" | "published" | "commitPending" = "starting";
|
||||
let transaction: GuardianTransaction | undefined;
|
||||
let terminal = false;
|
||||
let deadline: NodeJS.Timeout | undefined;
|
||||
let operations = Promise.resolve();
|
||||
const liveness = createReadStream("", { fd: 0, autoClose: false });
|
||||
|
||||
liveness.on("data", consumeChunk);
|
||||
liveness.once("end", () => {
|
||||
enqueue(async () => {
|
||||
if (state === "commitPending" && pending.byteLength === 0 && expectedBytes === undefined) {
|
||||
await succeedOnCommittedEof();
|
||||
return;
|
||||
}
|
||||
if (state === "starting" && pending.byteLength > 0) {
|
||||
await failClosed(126, "provider guardian frame is truncated");
|
||||
return;
|
||||
}
|
||||
await failClosed(125, "provider guardian liveness EOF");
|
||||
});
|
||||
});
|
||||
liveness.once("error", (error) => {
|
||||
enqueue(async () => failClosed(125, `provider guardian liveness error: ${error.message}`));
|
||||
});
|
||||
|
||||
async function initializeBootstrap(): Promise<BootstrapAuthority> {
|
||||
const rawDirectory = path.resolve(process.cwd(), "provider-evidence/untrusted");
|
||||
const evidenceDirectory = path.resolve(process.cwd(), "provider-evidence");
|
||||
const failures: Error[] = [];
|
||||
const rawDirectoryValid = captureInheritedDirectory(
|
||||
RAW_DIRECTORY_FD,
|
||||
rawDirectory,
|
||||
"raw",
|
||||
failures,
|
||||
);
|
||||
const evidenceDirectoryValid = captureInheritedDirectory(
|
||||
EVIDENCE_DIRECTORY_FD,
|
||||
evidenceDirectory,
|
||||
"evidence",
|
||||
failures,
|
||||
);
|
||||
|
||||
const rawDescriptor = capturePrivateDescriptor(RAW_STAGING_FD, "raw staging", failures);
|
||||
const sealedDescriptor = capturePrivateDescriptor(SEALED_TEMP_FD, "sealed temp", failures);
|
||||
const rawAuthority = rawDescriptor && rawDirectoryValid
|
||||
? capturePrivateAlias({
|
||||
descriptorMetadata: rawDescriptor,
|
||||
descriptorTarget: RAW_STAGING_FD_PATH,
|
||||
expectedDirectory: rawDirectory,
|
||||
descriptorDirectory: RAW_DIRECTORY_PATH,
|
||||
grammar: RAW_STAGING_PATTERN,
|
||||
label: "raw staging",
|
||||
}, failures)
|
||||
: undefined;
|
||||
const sealedAuthority = sealedDescriptor && evidenceDirectoryValid
|
||||
? capturePrivateAlias({
|
||||
descriptorMetadata: sealedDescriptor,
|
||||
descriptorTarget: SEALED_TEMP_FD_PATH,
|
||||
expectedDirectory: evidenceDirectory,
|
||||
descriptorDirectory: EVIDENCE_DIRECTORY_PATH,
|
||||
grammar: SEALED_TEMP_PATTERN,
|
||||
label: "sealed temp",
|
||||
}, failures)
|
||||
: undefined;
|
||||
|
||||
if (!rawAuthority || !sealedAuthority) {
|
||||
return await failBootstrap(rawAuthority, sealedAuthority, failures);
|
||||
}
|
||||
try {
|
||||
if (
|
||||
rawAuthority.stem !== sealedAuthority.stem ||
|
||||
rawAuthority.noncePrefix !== sealedAuthority.noncePrefix
|
||||
) {
|
||||
throw new TypeError("provider guardian inherited private aliases disagree");
|
||||
}
|
||||
const kind = providerKindFromStem(rawAuthority.stem);
|
||||
const rawLeaf = kind === "vulnerability"
|
||||
? "vulnerability-report.json"
|
||||
: "provenance-attestation.json";
|
||||
return Object.freeze({
|
||||
kind,
|
||||
noncePrefix: rawAuthority.noncePrefix,
|
||||
rawStagingLeaf: rawAuthority.leaf,
|
||||
rawStagingPath: rawAuthority.path,
|
||||
rawPath: `${RAW_DIRECTORY_PATH}/${rawLeaf}`,
|
||||
rawIdentity: rawAuthority.identity,
|
||||
sealedTempLeaf: sealedAuthority.leaf,
|
||||
sealedTempPath: sealedAuthority.path,
|
||||
sealedPath: `${EVIDENCE_DIRECTORY_PATH}/${rawLeaf}`,
|
||||
sealedIdentity: sealedAuthority.identity,
|
||||
});
|
||||
} catch (error) {
|
||||
failures.push(toError(error));
|
||||
return await failBootstrap(rawAuthority, sealedAuthority, failures);
|
||||
}
|
||||
}
|
||||
|
||||
function captureInheritedDirectory(
|
||||
fd: number,
|
||||
canonicalPath: string,
|
||||
label: string,
|
||||
failures: Error[],
|
||||
): boolean {
|
||||
try {
|
||||
assertInheritedDirectory(fd, canonicalPath, label);
|
||||
return true;
|
||||
} catch (error) {
|
||||
failures.push(toError(error));
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function capturePrivateDescriptor(
|
||||
fd: number,
|
||||
label: string,
|
||||
failures: Error[],
|
||||
): Stats | undefined {
|
||||
try {
|
||||
return fstatSync(fd);
|
||||
} catch (error) {
|
||||
failures.push(new Error(`provider guardian inherited ${label} fd is invalid`, {
|
||||
cause: error,
|
||||
}));
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function capturePrivateAlias(
|
||||
input: Readonly<{
|
||||
descriptorMetadata: Stats;
|
||||
descriptorTarget: string;
|
||||
expectedDirectory: string;
|
||||
descriptorDirectory: string;
|
||||
grammar: RegExp;
|
||||
label: string;
|
||||
}>,
|
||||
failures: Error[],
|
||||
): BoundPrivateAuthority | undefined {
|
||||
try {
|
||||
return bindPrivateAlias(input);
|
||||
} catch (error) {
|
||||
failures.push(toError(error));
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function bindPrivateAlias(input: Readonly<{
|
||||
descriptorMetadata: Stats;
|
||||
descriptorTarget: string;
|
||||
expectedDirectory: string;
|
||||
descriptorDirectory: string;
|
||||
grammar: RegExp;
|
||||
label: string;
|
||||
}>): BoundPrivateAuthority {
|
||||
const descriptorTarget = readlinkSync(input.descriptorTarget);
|
||||
if (path.dirname(descriptorTarget) !== input.expectedDirectory) {
|
||||
throw new TypeError(
|
||||
`provider guardian inherited ${input.label} alias is outside its directory`,
|
||||
);
|
||||
}
|
||||
const leaf = path.basename(descriptorTarget);
|
||||
const match = input.grammar.exec(leaf);
|
||||
if (!match) {
|
||||
throw new TypeError(`provider guardian inherited ${input.label} alias is invalid`);
|
||||
}
|
||||
const boundPath = `${input.descriptorDirectory}/${leaf}`;
|
||||
const pathnameMetadata = lstatSync(boundPath);
|
||||
assertPrivateMetadata(input.descriptorMetadata, pathnameMetadata, input.label);
|
||||
return Object.freeze({
|
||||
identity: Object.freeze({
|
||||
dev: input.descriptorMetadata.dev,
|
||||
ino: input.descriptorMetadata.ino,
|
||||
}),
|
||||
leaf,
|
||||
noncePrefix: match[2]!,
|
||||
path: boundPath,
|
||||
stem: match[1]!,
|
||||
});
|
||||
}
|
||||
|
||||
async function failBootstrap(
|
||||
rawAuthority: BoundPrivateAuthority | undefined,
|
||||
sealedAuthority: BoundPrivateAuthority | undefined,
|
||||
failures: Error[],
|
||||
): Promise<never> {
|
||||
for (const authority of [rawAuthority, sealedAuthority]) {
|
||||
if (!authority) continue;
|
||||
await cleanupOwnedPath(authority.path, authority.identity, failures);
|
||||
}
|
||||
closePrivateFds(failures);
|
||||
writeAggregateDiagnostic("provider guardian bootstrap failed", failures);
|
||||
process.exit(126);
|
||||
}
|
||||
|
||||
function assertPrivateMetadata(
|
||||
descriptorMetadata: Stats,
|
||||
pathnameMetadata: Stats,
|
||||
label: string,
|
||||
): void {
|
||||
if (
|
||||
!descriptorMetadata.isFile() || !pathnameMetadata.isFile() ||
|
||||
pathnameMetadata.isSymbolicLink() || descriptorMetadata.dev !== pathnameMetadata.dev ||
|
||||
descriptorMetadata.ino !== pathnameMetadata.ino || descriptorMetadata.nlink !== 1 ||
|
||||
pathnameMetadata.nlink !== 1 || (descriptorMetadata.mode & 0o777) !== 0o600 ||
|
||||
(pathnameMetadata.mode & 0o777) !== 0o600 || descriptorMetadata.size !== 0 ||
|
||||
pathnameMetadata.size !== 0
|
||||
) {
|
||||
throw new TypeError(`provider guardian inherited ${label} identity is invalid`);
|
||||
}
|
||||
}
|
||||
|
||||
function providerKindFromStem(stem: string): ProviderGuardianKind {
|
||||
if (stem === "vulnerability-report") return "vulnerability";
|
||||
if (stem === "provenance-attestation") return "provenance";
|
||||
throw new TypeError("provider guardian inherited private kind is invalid");
|
||||
}
|
||||
|
||||
function consumeChunk(chunk: Buffer | string): void {
|
||||
if (terminal) return;
|
||||
pending = Buffer.concat([pending, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
|
||||
if (expectedBytes === undefined && pending.byteLength >= 4) {
|
||||
expectedBytes = pending.readUInt32BE(0);
|
||||
if (expectedBytes <= 0 || expectedBytes > MAX_PROVIDER_GUARDIAN_FRAME_PAYLOAD_BYTES) {
|
||||
enqueue(async () => failClosed(126, "provider guardian frame length is invalid"));
|
||||
return;
|
||||
}
|
||||
}
|
||||
if (expectedBytes !== undefined && pending.byteLength === expectedBytes + 4) {
|
||||
const payload = pending.subarray(4);
|
||||
pending = Buffer.alloc(0);
|
||||
expectedBytes = undefined;
|
||||
enqueue(async () => handleFrame(payload));
|
||||
} else if (expectedBytes !== undefined && pending.byteLength > expectedBytes + 4) {
|
||||
enqueue(async () => failClosed(126, "provider guardian frame has trailing bytes"));
|
||||
}
|
||||
}
|
||||
|
||||
function enqueue(operation: () => Promise<void>): void {
|
||||
operations = operations.then(operation).catch(async (error) => {
|
||||
await failClosed(126, error instanceof Error ? error.message : String(error));
|
||||
});
|
||||
}
|
||||
|
||||
async function handleFrame(payload: Buffer): Promise<void> {
|
||||
if (state === "starting") {
|
||||
await establishTransaction(payload);
|
||||
} else if (state === "guarding") {
|
||||
await publishSealedArtifact(payload);
|
||||
} else if (state === "published") {
|
||||
await prepareCommit(payload);
|
||||
} else {
|
||||
await failClosed(126, "provider guardian received data after commit");
|
||||
}
|
||||
}
|
||||
|
||||
async function establishTransaction(payload: Buffer): Promise<void> {
|
||||
const nowEpochMs = Date.now();
|
||||
const guard = decodeProviderGuardianGuard(payload, {
|
||||
nowEpochMs,
|
||||
maxLeaseMs: MAX_PROVIDER_GUARDIAN_LEASE_MS,
|
||||
});
|
||||
if (
|
||||
guard.kind !== bootstrap.kind ||
|
||||
guard.nonce.subarray(0, 16).toString("hex") !== bootstrap.noncePrefix ||
|
||||
providerGuardianRawStagingLeaf(guard.kind, guard.nonce) !== bootstrap.rawStagingLeaf ||
|
||||
providerGuardianSealedTempLeaf(guard.kind, guard.nonce) !== bootstrap.sealedTempLeaf
|
||||
) {
|
||||
throw new TypeError("provider guardian guard does not match inherited private aliases");
|
||||
}
|
||||
assertBoundPrivateLeaf(
|
||||
RAW_STAGING_FD,
|
||||
bootstrap.rawStagingPath,
|
||||
bootstrap.rawIdentity,
|
||||
"raw staging",
|
||||
);
|
||||
assertBoundPrivateLeaf(
|
||||
SEALED_TEMP_FD,
|
||||
bootstrap.sealedTempPath,
|
||||
bootstrap.sealedIdentity,
|
||||
"sealed temp",
|
||||
);
|
||||
transaction = Object.freeze({ guard });
|
||||
|
||||
await link(bootstrap.rawStagingPath, bootstrap.rawPath);
|
||||
assertOwnedPathMetadata(bootstrap.rawStagingPath, bootstrap.rawIdentity, 2, 0o600, 0,
|
||||
"raw staging link");
|
||||
assertOwnedPathMetadata(bootstrap.rawPath, bootstrap.rawIdentity, 2, 0o600, 0,
|
||||
"canonical raw link");
|
||||
await unlink(bootstrap.rawStagingPath);
|
||||
fsyncSync(RAW_DIRECTORY_FD);
|
||||
assertOwnedPathMetadata(bootstrap.rawPath, bootstrap.rawIdentity, 1, 0o600, 0,
|
||||
"canonical raw");
|
||||
assertBoundPrivateLeaf(
|
||||
SEALED_TEMP_FD,
|
||||
bootstrap.sealedTempPath,
|
||||
bootstrap.sealedIdentity,
|
||||
"sealed temp",
|
||||
);
|
||||
|
||||
const remainingLeaseMs = guard.deadlineEpochMs - Date.now();
|
||||
if (remainingLeaseMs <= 0) {
|
||||
throw new TypeError("provider guardian guard deadline expired during startup");
|
||||
}
|
||||
deadline = setTimeout(() => {
|
||||
enqueue(async () => failClosed(124, "provider guardian lease deadline expired", true));
|
||||
}, remainingLeaseMs);
|
||||
writeSync(1, encodeProviderGuardianReady({
|
||||
nonce: guard.nonce,
|
||||
rawDev: bootstrap.rawIdentity.dev,
|
||||
rawIno: bootstrap.rawIdentity.ino,
|
||||
sealedTempLeaf: bootstrap.sealedTempLeaf,
|
||||
sealedDev: bootstrap.sealedIdentity.dev,
|
||||
sealedIno: bootstrap.sealedIdentity.ino,
|
||||
}));
|
||||
state = "guarding";
|
||||
}
|
||||
|
||||
function assertBoundPrivateLeaf(
|
||||
fd: number,
|
||||
target: string,
|
||||
identity: OwnedIdentity,
|
||||
label: string,
|
||||
): void {
|
||||
const descriptorMetadata = fstatSync(fd);
|
||||
const pathnameMetadata = lstatSync(target);
|
||||
assertOwnedMetadata(descriptorMetadata, identity, 1, 0o600, 0, label);
|
||||
assertOwnedMetadata(pathnameMetadata, identity, 1, 0o600, 0, label);
|
||||
if (pathnameMetadata.isSymbolicLink()) {
|
||||
throw new TypeError(`provider guardian ${label} alias became symbolic`);
|
||||
}
|
||||
}
|
||||
|
||||
async function publishSealedArtifact(payload: Buffer): Promise<void> {
|
||||
if (!transaction) {
|
||||
throw new Error("provider guardian transaction identity is unavailable");
|
||||
}
|
||||
const publication = decodeProviderGuardianPublish(payload, transaction.guard.nonce);
|
||||
if (
|
||||
publication.sealedDev !== bootstrap.sealedIdentity.dev ||
|
||||
publication.sealedIno !== bootstrap.sealedIdentity.ino
|
||||
) {
|
||||
throw new TypeError("provider guardian publish identity is invalid");
|
||||
}
|
||||
assertOwnedMetadata(
|
||||
fstatSync(SEALED_TEMP_FD),
|
||||
bootstrap.sealedIdentity,
|
||||
1,
|
||||
0o400,
|
||||
publication.size,
|
||||
"sealed publish descriptor",
|
||||
);
|
||||
const pathnameMetadata = await lstat(bootstrap.sealedTempPath);
|
||||
assertOwnedMetadata(
|
||||
pathnameMetadata,
|
||||
bootstrap.sealedIdentity,
|
||||
1,
|
||||
0o400,
|
||||
publication.size,
|
||||
"sealed publish pathname",
|
||||
);
|
||||
if (pathnameMetadata.isSymbolicLink()) {
|
||||
throw new TypeError("provider guardian sealed publish pathname became symbolic");
|
||||
}
|
||||
const actualSha256 = hashInheritedFile(SEALED_TEMP_FD, publication.size);
|
||||
if (actualSha256 !== publication.sha256) {
|
||||
throw new TypeError("provider guardian publish hash is invalid");
|
||||
}
|
||||
try {
|
||||
await lstat(bootstrap.sealedPath);
|
||||
throw new Error("provider guardian sealed output already exists");
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
}
|
||||
await link(bootstrap.sealedTempPath, bootstrap.sealedPath);
|
||||
await unlink(bootstrap.sealedTempPath);
|
||||
fsyncSync(EVIDENCE_DIRECTORY_FD);
|
||||
const finalMetadata = await lstat(bootstrap.sealedPath);
|
||||
assertOwnedMetadata(
|
||||
finalMetadata,
|
||||
bootstrap.sealedIdentity,
|
||||
1,
|
||||
0o400,
|
||||
publication.size,
|
||||
"sealed final",
|
||||
);
|
||||
if (finalMetadata.isSymbolicLink()) {
|
||||
throw new TypeError("provider guardian sealed final became symbolic");
|
||||
}
|
||||
state = "published";
|
||||
writeSync(1, encodeProviderGuardianPublished({
|
||||
nonce: transaction.guard.nonce,
|
||||
sealedDev: bootstrap.sealedIdentity.dev,
|
||||
sealedIno: bootstrap.sealedIdentity.ino,
|
||||
}));
|
||||
}
|
||||
|
||||
function assertOwnedPathMetadata(
|
||||
target: string,
|
||||
identity: OwnedIdentity,
|
||||
expectedLinks: number,
|
||||
expectedMode: number,
|
||||
expectedSize: number,
|
||||
label: string,
|
||||
): void {
|
||||
const metadata = lstatSync(target);
|
||||
assertOwnedMetadata(metadata, identity, expectedLinks, expectedMode, expectedSize, label);
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`provider guardian ${label} became symbolic`);
|
||||
}
|
||||
}
|
||||
|
||||
function assertOwnedMetadata(
|
||||
metadata: Stats,
|
||||
identity: OwnedIdentity,
|
||||
expectedLinks: number,
|
||||
expectedMode: number,
|
||||
expectedSize: number,
|
||||
label: string,
|
||||
): void {
|
||||
if (
|
||||
!metadata.isFile() || metadata.dev !== identity.dev || metadata.ino !== identity.ino ||
|
||||
metadata.nlink !== expectedLinks || (metadata.mode & 0o777) !== expectedMode ||
|
||||
metadata.size !== expectedSize
|
||||
) {
|
||||
throw new TypeError(`provider guardian ${label} metadata is invalid`);
|
||||
}
|
||||
}
|
||||
|
||||
function hashInheritedFile(fd: number, size: number): string {
|
||||
const digest = createHash("sha256");
|
||||
const buffer = Buffer.allocUnsafe(Math.min(65_536, size));
|
||||
let position = 0;
|
||||
while (position < size) {
|
||||
const requested = Math.min(buffer.byteLength, size - position);
|
||||
const bytesRead = readSync(fd, buffer, 0, requested, position);
|
||||
if (bytesRead <= 0) throw new Error("provider guardian sealed publish read was truncated");
|
||||
digest.update(buffer.subarray(0, bytesRead));
|
||||
position += bytesRead;
|
||||
}
|
||||
return digest.digest("hex");
|
||||
}
|
||||
|
||||
async function prepareCommit(payload: Buffer): Promise<void> {
|
||||
if (!transaction) throw new Error("provider guardian transaction identity is unavailable");
|
||||
decodeProviderGuardianCommit(payload, transaction.guard.nonce);
|
||||
const removedRaw = await cleanupOwnedProviderReport({
|
||||
reportPath: bootstrap.rawPath,
|
||||
reportDev: bootstrap.rawIdentity.dev,
|
||||
reportIno: bootstrap.rawIdentity.ino,
|
||||
});
|
||||
if (!removedRaw) throw new Error("provider guardian raw output disappeared before commit");
|
||||
state = "commitPending";
|
||||
}
|
||||
|
||||
async function succeedOnCommittedEof(): Promise<void> {
|
||||
const closeErrors: Error[] = [];
|
||||
closePrivateFds(closeErrors);
|
||||
if (closeErrors.length > 0) {
|
||||
await failClosed(
|
||||
126,
|
||||
"provider guardian private descriptor close failed",
|
||||
false,
|
||||
closeErrors,
|
||||
);
|
||||
return;
|
||||
}
|
||||
terminal = true;
|
||||
if (deadline) clearTimeout(deadline);
|
||||
liveness.removeAllListeners();
|
||||
liveness.destroy();
|
||||
closeControlInputBestEffort();
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
async function failClosed(
|
||||
exitCode: number,
|
||||
message: string,
|
||||
forceSignal = false,
|
||||
priorErrors: readonly Error[] = [],
|
||||
): Promise<void> {
|
||||
if (terminal) return;
|
||||
terminal = true;
|
||||
if (deadline) clearTimeout(deadline);
|
||||
liveness.removeAllListeners();
|
||||
liveness.destroy();
|
||||
const failures = [new Error(message), ...priorErrors];
|
||||
await cleanupOwnedPath(bootstrap.rawStagingPath, bootstrap.rawIdentity, failures);
|
||||
await cleanupOwnedPath(bootstrap.rawPath, bootstrap.rawIdentity, failures);
|
||||
await cleanupOwnedPath(bootstrap.sealedTempPath, bootstrap.sealedIdentity, failures);
|
||||
await cleanupOwnedPath(bootstrap.sealedPath, bootstrap.sealedIdentity, failures);
|
||||
closePrivateFds(failures);
|
||||
closeControlInputBestEffort();
|
||||
writeAggregateDiagnostic("provider guardian failed", failures);
|
||||
if (forceSignal) {
|
||||
try {
|
||||
process.kill(process.pid, "SIGKILL");
|
||||
} finally {
|
||||
process.exit(exitCode);
|
||||
}
|
||||
}
|
||||
process.exit(exitCode);
|
||||
}
|
||||
|
||||
async function cleanupOwnedPath(
|
||||
target: string,
|
||||
identity: OwnedIdentity,
|
||||
errors: Error[],
|
||||
): Promise<void> {
|
||||
try {
|
||||
await cleanupOwnedProviderReport({
|
||||
reportPath: target,
|
||||
reportDev: identity.dev,
|
||||
reportIno: identity.ino,
|
||||
});
|
||||
} catch (error) {
|
||||
errors.push(toError(error));
|
||||
}
|
||||
}
|
||||
|
||||
function closePrivateFds(errors: Error[]): void {
|
||||
if (privateFdsClosed) return;
|
||||
privateFdsClosed = true;
|
||||
for (const fd of [RAW_STAGING_FD, SEALED_TEMP_FD]) {
|
||||
try {
|
||||
closeSync(fd);
|
||||
} catch (error) {
|
||||
errors.push(toError(error));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function closeControlInputBestEffort(): void {
|
||||
try {
|
||||
closeSync(0);
|
||||
} catch {
|
||||
// Terminal cleanup and the exit status must not depend on a diagnostic fd.
|
||||
}
|
||||
}
|
||||
|
||||
function writeAggregateDiagnostic(label: string, failures: readonly Error[]): void {
|
||||
const aggregate = failures.length > 1
|
||||
? new AggregateError(failures, label, { cause: failures[0] })
|
||||
: failures[0];
|
||||
const detail = aggregate instanceof AggregateError
|
||||
? aggregate.errors.map((error) => toError(error).message).join("; ")
|
||||
: aggregate?.message ?? label;
|
||||
try {
|
||||
writeSync(2, `${label}: ${detail}\n`);
|
||||
} catch {
|
||||
// A closed parent-side pipe must not convert fail-closed termination to exit 0.
|
||||
}
|
||||
}
|
||||
|
||||
function assertInheritedDirectory(fd: number, canonicalPath: string, label: string): void {
|
||||
const descriptorMetadata = fstatSync(fd);
|
||||
const pathMetadata = lstatSync(canonicalPath);
|
||||
if (
|
||||
!descriptorMetadata.isDirectory() || !pathMetadata.isDirectory() ||
|
||||
pathMetadata.isSymbolicLink() || descriptorMetadata.dev !== pathMetadata.dev ||
|
||||
descriptorMetadata.ino !== pathMetadata.ino
|
||||
) {
|
||||
throw new TypeError(`provider guardian inherited ${label} fd is not a directory`);
|
||||
}
|
||||
}
|
||||
|
||||
function toError(error: unknown): Error {
|
||||
return error instanceof Error ? error : new Error(String(error));
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,213 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { closeSync, writeSync } from "node:fs";
|
||||
import { Socket } from "node:net";
|
||||
|
||||
import { cleanupOwnedProviderReport } from "./provider-raw-cleanup.ts";
|
||||
|
||||
const MAX_FRAME_BYTES = 16_777_216;
|
||||
const reportIdentity = parseReportIdentity(process.argv.slice(2));
|
||||
let pending = Buffer.alloc(0);
|
||||
let expectedBytes: number | undefined;
|
||||
let provider: ReturnType<typeof spawn> | undefined;
|
||||
let providerClosed = false;
|
||||
let livenessLost = false;
|
||||
/**
|
||||
* The supervisor keeps this pipe open for the scope's whole life — that is how
|
||||
* parent loss is observed — and only ever writes one frame into it.
|
||||
*
|
||||
* It must be read through libuv's event loop, not through `fs`. An `fs` read
|
||||
* runs a blocking `read(2)` on a threadpool thread, and on a pipe with a live
|
||||
* writer that call never returns. Closing the descriptor does not interrupt it,
|
||||
* so once bubblewrap exits the wrapper deadlocks in `process.exit` waiting to
|
||||
* join that thread: the scope outlives the provider, the supervisor's wall
|
||||
* clock expires, and a completed provider is reported as a timeout kill.
|
||||
*/
|
||||
const liveness = openLivenessChannel();
|
||||
|
||||
liveness.on("data", (chunk: Buffer | string) => {
|
||||
if (provider) {
|
||||
terminateForProtocolFailure("provider scope received trailing protocol bytes");
|
||||
return;
|
||||
}
|
||||
pending = Buffer.concat([pending, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
|
||||
if (expectedBytes === undefined && pending.byteLength >= 4) {
|
||||
expectedBytes = pending.readUInt32BE(0);
|
||||
if (expectedBytes <= 0 || expectedBytes > MAX_FRAME_BYTES) {
|
||||
terminateForProtocolFailure("provider scope frame length is invalid");
|
||||
return;
|
||||
}
|
||||
}
|
||||
if (expectedBytes !== undefined && pending.byteLength === expectedBytes + 4) {
|
||||
launchProvider(pending.subarray(4));
|
||||
pending = Buffer.alloc(0);
|
||||
} else if (expectedBytes !== undefined && pending.byteLength > expectedBytes + 4) {
|
||||
terminateForProtocolFailure("provider scope frame has trailing bytes");
|
||||
}
|
||||
});
|
||||
|
||||
liveness.once("end", () => terminateForParentLoss());
|
||||
liveness.once("error", () => terminateForParentLoss());
|
||||
|
||||
function launchProvider(payload: Buffer): void {
|
||||
const frame = parseFrame(payload);
|
||||
if (
|
||||
frame.reportPath !== reportIdentity.reportPath ||
|
||||
frame.reportDev !== reportIdentity.reportDev ||
|
||||
frame.reportIno !== reportIdentity.reportIno
|
||||
) {
|
||||
throw new TypeError("provider scope frame identity does not match its launch identity");
|
||||
}
|
||||
const bwrapInput = Buffer.from(frame.bwrapInputBase64, "base64");
|
||||
// The options are read from fd 0; the command must stay on real argv because
|
||||
// bubblewrap discards whatever follows the option stream inside an args file.
|
||||
provider = spawn("/usr/bin/bwrap", ["--args", "0", "--", ...frame.bwrapCommand], {
|
||||
detached: true,
|
||||
stdio: ["pipe", "inherit", "inherit"],
|
||||
});
|
||||
// bubblewrap can exit before the options are fully written — a usage error
|
||||
// closes fd 0 immediately. Without this the EPIPE would surface as an
|
||||
// unhandled stream error and the scope would be torn down as a crash rather
|
||||
// than reported as the provider exit it is.
|
||||
provider.stdin?.once("error", () => {});
|
||||
provider.stdin?.end(bwrapInput);
|
||||
provider.once("error", (error) => finishProvider(frame, null, null, error));
|
||||
provider.once("close", (code, signal) => finishProvider(frame, code, signal));
|
||||
}
|
||||
|
||||
async function finishProvider(
|
||||
frame: ReturnType<typeof parseFrame>,
|
||||
code: number | null,
|
||||
signal: NodeJS.Signals | null,
|
||||
error?: Error,
|
||||
): Promise<void> {
|
||||
if (providerClosed) return;
|
||||
providerClosed = true;
|
||||
if (livenessLost) await cleanupOwnedProviderReport(frame);
|
||||
closeLivenessInput();
|
||||
if (error) {
|
||||
writeSync(2, `${error.message}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
if (signal) process.exit(128 + signalNumber(signal));
|
||||
process.exit(code ?? 1);
|
||||
}
|
||||
|
||||
function terminateForParentLoss(): void {
|
||||
if (livenessLost) return;
|
||||
livenessLost = true;
|
||||
if (!provider || providerClosed) {
|
||||
void cleanupAfterParentLossAndExit();
|
||||
return;
|
||||
}
|
||||
try {
|
||||
process.kill(-provider.pid!, "SIGKILL");
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ESRCH")) throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function cleanupAfterParentLossAndExit(): Promise<void> {
|
||||
try {
|
||||
await cleanupOwnedProviderReport(reportIdentity);
|
||||
} catch (error) {
|
||||
writeSync(2, `${error instanceof Error ? error.message : String(error)}\n`);
|
||||
}
|
||||
closeLivenessInput();
|
||||
process.exit(125);
|
||||
}
|
||||
|
||||
function terminateForProtocolFailure(message: string): void {
|
||||
writeSync(2, `${message}\n`);
|
||||
terminateForParentLoss();
|
||||
}
|
||||
|
||||
function openLivenessChannel(): Socket {
|
||||
try {
|
||||
return new Socket({ fd: 0, readable: true, writable: false });
|
||||
} catch (error) {
|
||||
// Without an observable parent this process cannot be trusted to notice
|
||||
// supervisor loss, and an unsupervised sandbox is worse than no run.
|
||||
writeSync(2, `provider scope liveness channel is unavailable: ${
|
||||
error instanceof Error ? error.message : String(error)
|
||||
}\n`);
|
||||
process.exit(125);
|
||||
}
|
||||
}
|
||||
|
||||
function closeLivenessInput(): void {
|
||||
liveness.removeAllListeners();
|
||||
liveness.destroy();
|
||||
try {
|
||||
closeSync(0);
|
||||
} catch (error) {
|
||||
// `Socket.destroy()` owns the descriptor and closes it itself, so a second
|
||||
// close is expected rather than exceptional.
|
||||
if (!hasErrorCode(error, "EBADF")) throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function parseFrame(payload: Buffer): Readonly<{
|
||||
bwrapInputBase64: string;
|
||||
bwrapCommand: readonly string[];
|
||||
reportPath: string;
|
||||
reportDev: number;
|
||||
reportIno: number;
|
||||
}> {
|
||||
const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(payload)) as Record<string, unknown>;
|
||||
if (
|
||||
typeof value.bwrapInputBase64 !== "string" ||
|
||||
typeof value.reportPath !== "string" || !value.reportPath.startsWith("/") ||
|
||||
!Number.isSafeInteger(value.reportDev) || Number(value.reportDev) <= 0 ||
|
||||
!Number.isSafeInteger(value.reportIno) || Number(value.reportIno) <= 0
|
||||
) {
|
||||
throw new TypeError("provider scope frame payload is invalid");
|
||||
}
|
||||
assertBwrapCommand(value.bwrapCommand);
|
||||
return {
|
||||
bwrapInputBase64: value.bwrapInputBase64,
|
||||
bwrapCommand: Object.freeze([...value.bwrapCommand]),
|
||||
reportPath: value.reportPath,
|
||||
reportDev: Number(value.reportDev),
|
||||
reportIno: Number(value.reportIno),
|
||||
};
|
||||
}
|
||||
|
||||
function assertBwrapCommand(value: unknown): asserts value is readonly string[] {
|
||||
if (
|
||||
!Array.isArray(value) || value.length === 0 ||
|
||||
typeof value[0] !== "string" || !value[0].startsWith("/") ||
|
||||
value.some((argument) => typeof argument !== "string" || argument.includes("\0"))
|
||||
) {
|
||||
throw new TypeError("provider scope frame command is invalid");
|
||||
}
|
||||
}
|
||||
|
||||
function parseReportIdentity(arguments_: readonly string[]): Readonly<{
|
||||
cpuSeconds: number;
|
||||
reportPath: string;
|
||||
reportDev: number;
|
||||
reportIno: number;
|
||||
}> {
|
||||
const [cpuValue, reportPath, devValue, inoValue, ...trailing] = arguments_;
|
||||
const cpuSeconds = Number(cpuValue);
|
||||
const reportDev = Number(devValue);
|
||||
const reportIno = Number(inoValue);
|
||||
if (
|
||||
trailing.length > 0 ||
|
||||
!Number.isSafeInteger(cpuSeconds) || cpuSeconds <= 0 ||
|
||||
typeof reportPath !== "string" || !reportPath.startsWith("/") || reportPath.includes("\0") ||
|
||||
!Number.isSafeInteger(reportDev) || reportDev <= 0 ||
|
||||
!Number.isSafeInteger(reportIno) || reportIno <= 0
|
||||
) {
|
||||
throw new TypeError("provider scope launch identity is invalid");
|
||||
}
|
||||
return { cpuSeconds, reportPath, reportDev, reportIno };
|
||||
}
|
||||
|
||||
function signalNumber(signal: NodeJS.Signals): number {
|
||||
return signal === "SIGKILL" ? 9 : signal === "SIGXCPU" ? 24 : 1;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
import { randomBytes as cryptoRandomBytes } from "node:crypto";
|
||||
|
||||
import {
|
||||
captureCiCandidateArchive,
|
||||
withVerifiedCapturedCandidate,
|
||||
type CapturedCandidateArchive,
|
||||
} from "./ci-candidate-archive.ts";
|
||||
import { verifyArchivedLocalEvidence } from "./local-release-evidence.ts";
|
||||
import type { ExpectedPromotionContext, ProviderTrust } from "./provider-evidence.ts";
|
||||
import { validateProviderUpload } from "./provider-upload-validator.ts";
|
||||
|
||||
export type ProviderInvocation = Readonly<{
|
||||
candidateRoot: string;
|
||||
environment: Readonly<Record<string, string>>;
|
||||
}>;
|
||||
|
||||
export async function superviseProviderEvidence(input: Readonly<{
|
||||
kind: "vulnerability" | "provenance";
|
||||
archivePath: string;
|
||||
expectedArchiveSha256: string;
|
||||
expectedRun: Readonly<{ id: string; attempt: number; sourceRevision: string }>;
|
||||
trust: ProviderTrust;
|
||||
executeProvider: (invocation: ProviderInvocation) => Promise<void>;
|
||||
captureReport: () => Promise<Buffer>;
|
||||
}>, dependencies: Readonly<{
|
||||
captureArchive?: typeof captureCiCandidateArchive;
|
||||
withVerifiedCandidate?: typeof withVerifiedCapturedCandidate;
|
||||
verifyLocalEvidence?: typeof verifyArchivedLocalEvidence;
|
||||
validateUpload?: typeof validateProviderUpload;
|
||||
randomBytes?: (bytes: number) => Buffer;
|
||||
nowEpochMs?: () => number;
|
||||
}> = {}): Promise<Readonly<{
|
||||
evidence: unknown;
|
||||
invocationNonce: string;
|
||||
expectedContext: ExpectedPromotionContext;
|
||||
}>> {
|
||||
const captured = await (dependencies.captureArchive ?? captureCiCandidateArchive)({
|
||||
archivePath: input.archivePath,
|
||||
expectedSha256: input.expectedArchiveSha256,
|
||||
});
|
||||
const nonceBytes = (dependencies.randomBytes ?? cryptoRandomBytes)(32);
|
||||
if (nonceBytes.byteLength !== 32) {
|
||||
throw new TypeError("provider invocation nonce must contain exactly 32 bytes");
|
||||
}
|
||||
const invocationNonce = nonceBytes.toString("hex");
|
||||
const nowEpochMs = dependencies.nowEpochMs ?? Date.now;
|
||||
const result = await (dependencies.withVerifiedCandidate ?? withVerifiedCapturedCandidate)({
|
||||
captured,
|
||||
verify: async ({ extractionRoot, manifest }) => {
|
||||
const local = await (dependencies.verifyLocalEvidence ?? verifyArchivedLocalEvidence)({
|
||||
extractionRoot,
|
||||
expectedManifest: manifest,
|
||||
});
|
||||
if (local.status !== "PASS" || !local.identity) {
|
||||
throw new Error(
|
||||
`provider candidate local assessment failed: ${local.failures.join("; ")}`,
|
||||
);
|
||||
}
|
||||
if (local.identity.sourceRevision !== input.expectedRun.sourceRevision) {
|
||||
throw new Error("provider candidate source revision mismatch");
|
||||
}
|
||||
const expectedContext: ExpectedPromotionContext = Object.freeze({
|
||||
run: Object.freeze({ id: input.expectedRun.id, attempt: input.expectedRun.attempt }),
|
||||
source: Object.freeze({
|
||||
revision: local.identity.sourceRevision,
|
||||
sourceSetSha256: local.identity.sourceSetSha256,
|
||||
}),
|
||||
candidate: Object.freeze({
|
||||
archiveSha256: captured.archiveSha256,
|
||||
bundleSha256: manifest.bundleSha256,
|
||||
distSha256: manifest.distSha256,
|
||||
lockfileSha256: manifest.lockfileSha256,
|
||||
}),
|
||||
secretScanAttestation: Object.freeze({
|
||||
status: "PASS" as const,
|
||||
localEvidenceAssessmentSha256: local.identity.assessmentSha256,
|
||||
sourceSetSha256: local.identity.sourceSetSha256,
|
||||
policySha256: local.identity.secretScan.policySha256,
|
||||
sarifSha256: local.identity.secretScan.sarifSha256,
|
||||
scanInputSha256: local.identity.secretScan.scanInputSha256,
|
||||
}),
|
||||
vulnerabilityInvocationNonce:
|
||||
input.kind === "vulnerability" ? invocationNonce : "0".repeat(64),
|
||||
provenanceInvocationNonce:
|
||||
input.kind === "provenance" ? invocationNonce : "0".repeat(64),
|
||||
});
|
||||
const issuedNow = nowEpochMs();
|
||||
const issuedAt = new Date(issuedNow).toISOString();
|
||||
const expiresAt = new Date(issuedNow + 60 * 60 * 1_000).toISOString();
|
||||
await input.executeProvider({
|
||||
candidateRoot: extractionRoot,
|
||||
environment: providerInvocationEnvironment({
|
||||
kind: input.kind,
|
||||
expectedContext,
|
||||
invocationNonce,
|
||||
issuedAt,
|
||||
expiresAt,
|
||||
trust: input.trust,
|
||||
}),
|
||||
});
|
||||
const capturedReport = await input.captureReport();
|
||||
const evidence = await (dependencies.validateUpload ?? validateProviderUpload)({
|
||||
kind: input.kind,
|
||||
verifiedManifest: manifest,
|
||||
archiveSha256: captured.archiveSha256,
|
||||
candidateRoot: extractionRoot,
|
||||
capturedReport,
|
||||
expectedContext,
|
||||
trust: input.trust,
|
||||
nowEpochMs,
|
||||
});
|
||||
return Object.freeze({ evidence, invocationNonce, expectedContext });
|
||||
},
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
export function providerInvocationEnvironment(input: Readonly<{
|
||||
kind: "vulnerability" | "provenance";
|
||||
expectedContext: ExpectedPromotionContext;
|
||||
invocationNonce: string;
|
||||
issuedAt: string;
|
||||
expiresAt: string;
|
||||
trust: ProviderTrust;
|
||||
}>): Readonly<Record<string, string>> {
|
||||
return Object.freeze({
|
||||
PROVIDER_EVIDENCE_SCHEMA_VERSION: "2",
|
||||
PROVIDER_EVIDENCE_TYPE:
|
||||
input.kind === "vulnerability"
|
||||
? "vulnerability-report"
|
||||
: "provenance-attestation",
|
||||
PROVIDER_ISSUED_AT: input.issuedAt,
|
||||
PROVIDER_EXPIRES_AT: input.expiresAt,
|
||||
PROVIDER_INVOCATION_NONCE: input.invocationNonce,
|
||||
PROVIDER_KEY_ID: input.trust.keyId,
|
||||
PROVIDER_PUBLIC_KEY_FINGERPRINT: input.trust.publicKeyFingerprint,
|
||||
CI_RUN_ID: input.expectedContext.run.id,
|
||||
CI_RUN_ATTEMPT: String(input.expectedContext.run.attempt),
|
||||
SOURCE_REVISION: input.expectedContext.source.revision,
|
||||
SOURCE_SET_SHA256: input.expectedContext.source.sourceSetSha256,
|
||||
CANDIDATE_ROOT: "/candidate",
|
||||
CANDIDATE_LOCKFILE_PATH: "/candidate/pnpm-lock.yaml",
|
||||
CANDIDATE_ARCHIVE_SHA256: input.expectedContext.candidate.archiveSha256,
|
||||
CANDIDATE_BUNDLE_SHA256: input.expectedContext.candidate.bundleSha256,
|
||||
CANDIDATE_DIST_SHA256: input.expectedContext.candidate.distSha256,
|
||||
CANDIDATE_LOCKFILE_SHA256: input.expectedContext.candidate.lockfileSha256,
|
||||
SECRET_SCAN_STATUS: input.expectedContext.secretScanAttestation.status,
|
||||
SECRET_SCAN_LOCAL_EVIDENCE_ASSESSMENT_SHA256:
|
||||
input.expectedContext.secretScanAttestation.localEvidenceAssessmentSha256,
|
||||
SECRET_SCAN_SOURCE_SET_SHA256:
|
||||
input.expectedContext.secretScanAttestation.sourceSetSha256,
|
||||
SECRET_SCAN_POLICY_SHA256:
|
||||
input.expectedContext.secretScanAttestation.policySha256,
|
||||
SECRET_SCAN_SARIF_SHA256:
|
||||
input.expectedContext.secretScanAttestation.sarifSha256,
|
||||
SECRET_SCAN_INPUT_SHA256:
|
||||
input.expectedContext.secretScanAttestation.scanInputSha256,
|
||||
});
|
||||
}
|
||||
|
||||
export type CaptureArchiveDependency = (
|
||||
input: Readonly<{ archivePath: string; expectedSha256: string }>,
|
||||
) => Promise<CapturedCandidateArchive>;
|
||||
@@ -0,0 +1,42 @@
|
||||
import { createPublicKey } from "node:crypto";
|
||||
import path from "node:path";
|
||||
|
||||
import { readBoundedRegularFile } from "./ci-artifact-validator.ts";
|
||||
import {
|
||||
providerPublicKeyFingerprint,
|
||||
type ProviderTrust,
|
||||
} from "./provider-evidence.ts";
|
||||
|
||||
export async function readProviderTrust(
|
||||
configuredRoot: string,
|
||||
publicKeyPath: string | undefined,
|
||||
keyId: string | undefined,
|
||||
): Promise<ProviderTrust | null> {
|
||||
if (!publicKeyPath || !keyId?.trim()) return null;
|
||||
try {
|
||||
const root = path.resolve(configuredRoot);
|
||||
const absolute = path.resolve(root, publicKeyPath);
|
||||
const relative = path.relative(root, absolute);
|
||||
const outside =
|
||||
relative === ".." ||
|
||||
relative.startsWith(`..${path.sep}`) ||
|
||||
path.isAbsolute(relative);
|
||||
const bytes = await readBoundedRegularFile({
|
||||
root: outside ? path.dirname(absolute) : root,
|
||||
relativePath: outside
|
||||
? path.basename(absolute)
|
||||
: relative.replaceAll(path.sep, "/"),
|
||||
maxBytes: 1_048_576,
|
||||
});
|
||||
const publicKey = createPublicKey(
|
||||
new TextDecoder("utf-8", { fatal: true }).decode(bytes),
|
||||
);
|
||||
return Object.freeze({
|
||||
keyId,
|
||||
publicKey,
|
||||
publicKeyFingerprint: providerPublicKeyFingerprint(publicKey),
|
||||
});
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
import {
|
||||
validateProviderEvidence,
|
||||
type ExpectedPromotionContext,
|
||||
type ProviderTrust,
|
||||
} from "./provider-evidence.ts";
|
||||
import {
|
||||
verifyReleaseCandidate,
|
||||
type ReleaseCandidateManifest,
|
||||
} from "./release-candidate.ts";
|
||||
|
||||
export async function validateProviderUpload(input: Readonly<{
|
||||
kind: "vulnerability" | "provenance";
|
||||
verifiedManifest: ReleaseCandidateManifest;
|
||||
archiveSha256: string;
|
||||
candidateRoot: string;
|
||||
capturedReport: Buffer;
|
||||
expectedContext: ExpectedPromotionContext;
|
||||
trust: ProviderTrust;
|
||||
nowEpochMs?: () => number;
|
||||
}>): Promise<unknown> {
|
||||
if (
|
||||
input.expectedContext.candidate.archiveSha256 !== input.archiveSha256 ||
|
||||
input.expectedContext.candidate.bundleSha256 !== input.verifiedManifest.bundleSha256 ||
|
||||
input.expectedContext.candidate.distSha256 !== input.verifiedManifest.distSha256 ||
|
||||
input.expectedContext.candidate.lockfileSha256 !== input.verifiedManifest.lockfileSha256
|
||||
) {
|
||||
throw new Error("provider supervisor expected candidate context mismatch");
|
||||
}
|
||||
const verifiedCandidate = await verifyReleaseCandidate(
|
||||
input.verifiedManifest,
|
||||
input.candidateRoot,
|
||||
);
|
||||
if (verifiedCandidate.failures.length > 0) {
|
||||
throw new Error(
|
||||
`provider input candidate root changed: ${verifiedCandidate.failures.join("; ")}`,
|
||||
);
|
||||
}
|
||||
let report: unknown;
|
||||
try {
|
||||
report = JSON.parse(
|
||||
new TextDecoder("utf-8", { fatal: true }).decode(input.capturedReport),
|
||||
) as unknown;
|
||||
} catch {
|
||||
throw new TypeError("provider output is not canonical UTF-8 JSON");
|
||||
}
|
||||
const evaluated = validateProviderEvidence({
|
||||
kind: input.kind,
|
||||
value: report,
|
||||
expected: input.expectedContext,
|
||||
trust: input.trust,
|
||||
nowEpochMs: input.nowEpochMs,
|
||||
});
|
||||
if (evaluated.status !== "PASS" || !evaluated.evidence) {
|
||||
throw new Error(
|
||||
`provider evidence context validation failed: ${evaluated.failures.join("; ")}`,
|
||||
);
|
||||
}
|
||||
return evaluated.evidence;
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
import { readFile, readdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
export type RealtimeBoundaryRuleId =
|
||||
| "NATIVE_REALTIME_API_OUTSIDE_ADAPTER"
|
||||
| "PRESENTATION_INTERVAL_OWNER"
|
||||
| "UNSELECTED_REALTIME_RUNTIME_COMPOSED";
|
||||
|
||||
export type RealtimeBoundaryViolation = Readonly<{
|
||||
ruleId: RealtimeBoundaryRuleId;
|
||||
file: string;
|
||||
line: number;
|
||||
}>;
|
||||
|
||||
const SOURCE_EXTENSION = /\.(?:[cm]?ts|tsx)$/u;
|
||||
const OWNED_NATIVE_ROOTS = [
|
||||
"src/adapters/realtime/",
|
||||
"src/adapters/web-push/",
|
||||
] as const;
|
||||
const REALTIME_ADAPTER_IMPORT =
|
||||
/(?:from\s*|import\s*\()\s*["'][^"']*\/adapters\/(?:realtime|web-push)(?:\/[^"']*)?["']/gu;
|
||||
const NATIVE_REALTIME_PATTERNS = [
|
||||
/\bnew\s+(?:WebSocket|EventSource|Notification)\s*\(/gu,
|
||||
/\bNotification\s*\.\s*requestPermission\s*\(/gu,
|
||||
/\.\s*showNotification\s*\(/gu,
|
||||
/\.\s*pushManager\s*\.\s*(?:subscribe|getSubscription)\s*\(/gu,
|
||||
/\bReflect\s*\.\s*get\s*\([^,]+,\s*["'](?:WebSocket|EventSource|Notification|pushManager)["']/gu,
|
||||
] as const;
|
||||
const PRESENTATION_INTERVAL = /\bsetInterval\s*\(/gu;
|
||||
|
||||
export async function scanRealtimeBoundaries(
|
||||
sourceRoot: string,
|
||||
): Promise<readonly RealtimeBoundaryViolation[]> {
|
||||
const absoluteRoot = path.resolve(sourceRoot);
|
||||
const files = await collectSourceFiles(absoluteRoot);
|
||||
const violations: RealtimeBoundaryViolation[] = [];
|
||||
for (const file of files) {
|
||||
const source = await readFile(file, "utf8");
|
||||
const logicalFile = logicalSourcePath(absoluteRoot, file);
|
||||
inspectFile(source, logicalFile, violations);
|
||||
}
|
||||
return Object.freeze(
|
||||
violations
|
||||
.sort(
|
||||
(left, right) =>
|
||||
left.file.localeCompare(right.file) ||
|
||||
left.line - right.line ||
|
||||
left.ruleId.localeCompare(right.ruleId),
|
||||
)
|
||||
.map((violation) => Object.freeze(violation)),
|
||||
);
|
||||
}
|
||||
|
||||
function inspectFile(
|
||||
source: string,
|
||||
logicalFile: string,
|
||||
violations: RealtimeBoundaryViolation[],
|
||||
): void {
|
||||
const nativeOwned = OWNED_NATIVE_ROOTS.some((root) =>
|
||||
logicalFile.startsWith(root),
|
||||
);
|
||||
const presentationOwned =
|
||||
logicalFile.startsWith("src/presentation/") ||
|
||||
/^src\/features\/[^/]+\/presentation\//u.test(logicalFile);
|
||||
const compositionBoundary =
|
||||
logicalFile.startsWith("src/bootstrap/") ||
|
||||
/^src\/features\/installed-feature-/u.test(logicalFile);
|
||||
|
||||
const report = (
|
||||
ruleId: RealtimeBoundaryRuleId,
|
||||
index: number,
|
||||
): void => {
|
||||
violations.push({
|
||||
ruleId,
|
||||
file: logicalFile,
|
||||
line: lineAt(source, index),
|
||||
});
|
||||
};
|
||||
|
||||
if (!nativeOwned) {
|
||||
for (const pattern of NATIVE_REALTIME_PATTERNS) {
|
||||
for (const match of source.matchAll(pattern)) {
|
||||
report(
|
||||
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
|
||||
match.index,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (presentationOwned) {
|
||||
for (const match of source.matchAll(PRESENTATION_INTERVAL)) {
|
||||
report("PRESENTATION_INTERVAL_OWNER", match.index);
|
||||
}
|
||||
}
|
||||
if (compositionBoundary) {
|
||||
for (const match of source.matchAll(REALTIME_ADAPTER_IMPORT)) {
|
||||
report("UNSELECTED_REALTIME_RUNTIME_COMPOSED", match.index);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function collectSourceFiles(
|
||||
directory: string,
|
||||
): Promise<readonly string[]> {
|
||||
const output: string[] = [];
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
const resolved = path.join(directory, entry.name);
|
||||
if (
|
||||
entry.isDirectory() &&
|
||||
!["node_modules", "dist", "artifacts", ".tmp"].includes(
|
||||
entry.name,
|
||||
)
|
||||
) {
|
||||
output.push(...(await collectSourceFiles(resolved)));
|
||||
} else if (entry.isFile() && SOURCE_EXTENSION.test(entry.name)) {
|
||||
output.push(resolved);
|
||||
}
|
||||
}
|
||||
return output;
|
||||
}
|
||||
|
||||
function logicalSourcePath(root: string, file: string): string {
|
||||
const workspaceRelative = path
|
||||
.relative(process.cwd(), file)
|
||||
.split(path.sep)
|
||||
.join("/");
|
||||
if (root === path.resolve("src")) return workspaceRelative;
|
||||
return path.relative(root, file).split(path.sep).join("/");
|
||||
}
|
||||
|
||||
function lineAt(source: string, index: number): number {
|
||||
let line = 1;
|
||||
for (let offset = 0; offset < index; offset += 1) {
|
||||
if (source.charCodeAt(offset) === 10) line += 1;
|
||||
}
|
||||
return line;
|
||||
}
|
||||
@@ -0,0 +1,336 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
export const COMPATIBILITY_IMPACTS = Object.freeze([
|
||||
"none",
|
||||
"additive",
|
||||
"behavior-change",
|
||||
"breaking",
|
||||
] as const);
|
||||
|
||||
type CompatibilityImpact = (typeof COMPATIBILITY_IMPACTS)[number];
|
||||
type RegistryRecord = Record<string, unknown> & {
|
||||
registryId?: unknown;
|
||||
contract?: unknown;
|
||||
rows?: unknown;
|
||||
};
|
||||
type RegistryChange = {
|
||||
changeId: string;
|
||||
registryId: string;
|
||||
rowName: string;
|
||||
field: string;
|
||||
kind: string;
|
||||
impact: CompatibilityImpact;
|
||||
before?: unknown;
|
||||
after?: unknown;
|
||||
};
|
||||
type RegistryDiff = Readonly<{
|
||||
impact: CompatibilityImpact;
|
||||
changes: readonly RegistryChange[];
|
||||
}>;
|
||||
|
||||
const impactRank = new Map(
|
||||
COMPATIBILITY_IMPACTS.map((impact, index) => [impact, index]),
|
||||
);
|
||||
|
||||
export function canonicalizeRegistryValue(value: unknown): unknown {
|
||||
if (Array.isArray(value)) {
|
||||
const projected: unknown[] = value.map(canonicalizeRegistryValue);
|
||||
return projected.every(
|
||||
(item) =>
|
||||
item === null ||
|
||||
["string", "number", "boolean"].includes(typeof item),
|
||||
)
|
||||
? projected.sort((left, right) =>
|
||||
JSON.stringify(left).localeCompare(JSON.stringify(right)),
|
||||
)
|
||||
: projected;
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, item]) => [key, canonicalizeRegistryValue(item)]),
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
export function canonicalRegistryJson(value: unknown): string {
|
||||
return JSON.stringify(canonicalizeRegistryValue(value)) ?? "undefined";
|
||||
}
|
||||
|
||||
export function registrySnapshotDigest(snapshot: unknown): string {
|
||||
return createHash("sha256")
|
||||
.update(canonicalRegistryJson(snapshot))
|
||||
.digest("hex");
|
||||
}
|
||||
|
||||
function strongestImpact(
|
||||
current: CompatibilityImpact,
|
||||
candidate: CompatibilityImpact,
|
||||
): CompatibilityImpact {
|
||||
return (impactRank.get(candidate) ?? 0) > (impactRank.get(current) ?? 0)
|
||||
? candidate
|
||||
: current;
|
||||
}
|
||||
|
||||
function valueType(value: unknown): string {
|
||||
if (value === null) return "null";
|
||||
if (Array.isArray(value)) return "array";
|
||||
return typeof value;
|
||||
}
|
||||
|
||||
function changeId(
|
||||
registryId: string,
|
||||
rowName: string,
|
||||
field: string,
|
||||
kind: string,
|
||||
): string {
|
||||
return `${registryId}:${rowName}:${field}:${kind}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculates a semantic diff. Object key and primitive-array ordering is
|
||||
* canonicalized before comparison and therefore cannot create a false change.
|
||||
*/
|
||||
export function diffRegistrySnapshots(
|
||||
before: Readonly<Record<string, unknown>>,
|
||||
after: Readonly<Record<string, unknown>>,
|
||||
): RegistryDiff {
|
||||
const changes: RegistryChange[] = [];
|
||||
let impact: CompatibilityImpact = "none";
|
||||
const beforeRegistryRows = (before.registries ?? []) as RegistryRecord[];
|
||||
const beforeRegistries = new Map<string, RegistryRecord>(
|
||||
beforeRegistryRows.map((registry) => [
|
||||
String(registry.registryId),
|
||||
registry,
|
||||
]),
|
||||
);
|
||||
const afterRegistryRows = (after.registries ?? []) as RegistryRecord[];
|
||||
const afterRegistries = new Map<string, RegistryRecord>(
|
||||
afterRegistryRows.map((registry) => [
|
||||
String(registry.registryId),
|
||||
registry,
|
||||
]),
|
||||
);
|
||||
const registryIds = new Set([
|
||||
...beforeRegistries.keys(),
|
||||
...afterRegistries.keys(),
|
||||
]);
|
||||
|
||||
for (const registryId of [...registryIds].sort()) {
|
||||
const previous = beforeRegistries.get(registryId);
|
||||
const current = afterRegistries.get(registryId);
|
||||
if (!previous || !current) {
|
||||
const changeImpact = previous ? "breaking" : "additive";
|
||||
impact = strongestImpact(impact, changeImpact);
|
||||
changes.push({
|
||||
changeId: changeId(registryId, "*", "*", previous ? "removed" : "added"),
|
||||
registryId,
|
||||
rowName: "*",
|
||||
field: "*",
|
||||
kind: previous ? "registry-removed" : "registry-added",
|
||||
impact: changeImpact,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
const previousContract = (previous.contract ?? {}) as Record<string, unknown>;
|
||||
const currentContract = (current.contract ?? {}) as Record<string, unknown>;
|
||||
const contractFields = new Set([
|
||||
...Object.keys(previousContract),
|
||||
...Object.keys(currentContract),
|
||||
]);
|
||||
for (const field of [...contractFields].sort()) {
|
||||
const beforeHas = Object.hasOwn(previousContract, field);
|
||||
const afterHas = Object.hasOwn(currentContract, field);
|
||||
const beforeValue = previousContract[field];
|
||||
const afterValue = currentContract[field];
|
||||
if (
|
||||
beforeHas &&
|
||||
afterHas &&
|
||||
canonicalRegistryJson(beforeValue) ===
|
||||
canonicalRegistryJson(afterValue)
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
const kind = !beforeHas
|
||||
? "contract-field-added"
|
||||
: !afterHas
|
||||
? "contract-field-removed"
|
||||
: "contract-field-changed";
|
||||
impact = strongestImpact(impact, "breaking");
|
||||
changes.push({
|
||||
changeId: changeId(registryId, "$contract", field, kind),
|
||||
registryId,
|
||||
rowName: "$contract",
|
||||
field,
|
||||
kind,
|
||||
impact: "breaking",
|
||||
before: canonicalizeRegistryValue(beforeValue),
|
||||
after: canonicalizeRegistryValue(afterValue),
|
||||
});
|
||||
}
|
||||
|
||||
const breakingFields = new Set(
|
||||
(currentContract.breakingFields ?? []) as string[],
|
||||
);
|
||||
const beforeRows = (previous.rows ?? {}) as Record<
|
||||
string,
|
||||
Record<string, unknown>
|
||||
>;
|
||||
const afterRows = (current.rows ?? {}) as Record<
|
||||
string,
|
||||
Record<string, unknown>
|
||||
>;
|
||||
const rowNames = new Set([
|
||||
...Object.keys(beforeRows),
|
||||
...Object.keys(afterRows),
|
||||
]);
|
||||
for (const rowName of [...rowNames].sort()) {
|
||||
const beforeRow = beforeRows[rowName];
|
||||
const afterRow = afterRows[rowName];
|
||||
if (!beforeRow || !afterRow) {
|
||||
const changeImpact = beforeRow ? "breaking" : "additive";
|
||||
impact = strongestImpact(impact, changeImpact);
|
||||
changes.push({
|
||||
changeId: changeId(
|
||||
registryId,
|
||||
rowName,
|
||||
"*",
|
||||
beforeRow ? "removed" : "added",
|
||||
),
|
||||
registryId,
|
||||
rowName,
|
||||
field: "*",
|
||||
kind: beforeRow ? "row-removed" : "row-added",
|
||||
impact: changeImpact,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
const fields = new Set([
|
||||
...Object.keys(beforeRow),
|
||||
...Object.keys(afterRow),
|
||||
]);
|
||||
for (const field of [...fields].sort()) {
|
||||
const beforeHas = Object.hasOwn(beforeRow, field);
|
||||
const afterHas = Object.hasOwn(afterRow, field);
|
||||
const beforeValue = beforeRow[field];
|
||||
const afterValue = afterRow[field];
|
||||
if (
|
||||
beforeHas &&
|
||||
afterHas &&
|
||||
canonicalRegistryJson(beforeValue) ===
|
||||
canonicalRegistryJson(afterValue)
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
let kind: string;
|
||||
let changeImpact: CompatibilityImpact;
|
||||
if (!beforeHas) {
|
||||
kind = "field-added";
|
||||
changeImpact = "additive";
|
||||
} else if (!afterHas) {
|
||||
kind = "field-removed";
|
||||
changeImpact = "breaking";
|
||||
} else if (valueType(beforeValue) !== valueType(afterValue)) {
|
||||
kind = "field-type-changed";
|
||||
changeImpact = "breaking";
|
||||
} else if (
|
||||
Array.isArray(beforeValue) &&
|
||||
Array.isArray(afterValue) &&
|
||||
beforeValue.some(
|
||||
(item) =>
|
||||
!afterValue.some(
|
||||
(candidate) =>
|
||||
canonicalRegistryJson(candidate) ===
|
||||
canonicalRegistryJson(item),
|
||||
),
|
||||
)
|
||||
) {
|
||||
kind = "allowed-value-removed";
|
||||
changeImpact = "breaking";
|
||||
} else {
|
||||
kind = "field-changed";
|
||||
changeImpact = breakingFields.has(field)
|
||||
? "breaking"
|
||||
: "behavior-change";
|
||||
}
|
||||
impact = strongestImpact(impact, changeImpact);
|
||||
changes.push({
|
||||
changeId: changeId(registryId, rowName, field, kind),
|
||||
registryId,
|
||||
rowName,
|
||||
field,
|
||||
kind,
|
||||
impact: changeImpact,
|
||||
before: canonicalizeRegistryValue(beforeValue),
|
||||
after: canonicalizeRegistryValue(afterValue),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
impact,
|
||||
changes: Object.freeze(changes),
|
||||
});
|
||||
}
|
||||
|
||||
export function verifyRegistryBaselineApproval(
|
||||
snapshot: Readonly<Record<string, unknown>>,
|
||||
approval: Readonly<Record<string, unknown>>,
|
||||
) {
|
||||
const actualDigest = registrySnapshotDigest(snapshot);
|
||||
const approvedDigest = approval.snapshotDigest;
|
||||
return Object.freeze({
|
||||
passed:
|
||||
approval.schemaVersion === 1 &&
|
||||
typeof approval.owner === "string" &&
|
||||
approval.owner.length > 0 &&
|
||||
typeof approval.approvedAt === "string" &&
|
||||
approvedDigest === actualDigest,
|
||||
actualDigest,
|
||||
approvedDigest:
|
||||
typeof approvedDigest === "string" ? approvedDigest : "missing",
|
||||
});
|
||||
}
|
||||
|
||||
export function validateBreakingEvidence(
|
||||
diff: RegistryDiff,
|
||||
evidenceFile: Readonly<Record<string, unknown>>,
|
||||
) {
|
||||
const entries = (evidenceFile.changes ?? []) as Array<Record<string, unknown>>;
|
||||
const evidence = new Map<string, Record<string, unknown>>(
|
||||
entries.map((entry) => [String(entry.changeId), entry]),
|
||||
);
|
||||
const failures: string[] = [];
|
||||
for (const change of diff.changes.filter(
|
||||
(entry) => entry.impact === "breaking",
|
||||
)) {
|
||||
const entry = evidence.get(change.changeId);
|
||||
if (!entry) {
|
||||
failures.push(`breaking change missing evidence: ${change.changeId}`);
|
||||
continue;
|
||||
}
|
||||
for (const field of [
|
||||
"versionBump",
|
||||
"migration",
|
||||
"compatibilityWindow",
|
||||
"rollback",
|
||||
"owner",
|
||||
]) {
|
||||
const value = entry[field];
|
||||
if (typeof value !== "string" || value.trim().length === 0) {
|
||||
failures.push(
|
||||
`breaking change ${change.changeId} missing non-empty ${field}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,261 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { lstat, readFile, readdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { gzipSync } from "node:zlib";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import { supplyChainDigest } from "./supply-chain.ts";
|
||||
|
||||
const sha256 = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const candidateFileSchema = z
|
||||
.object({
|
||||
path: z.string().min(1),
|
||||
bytes: z.int().nonnegative(),
|
||||
sha256,
|
||||
})
|
||||
.strict();
|
||||
|
||||
export const releaseCandidateManifestSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
distSha256: sha256,
|
||||
lockfileSha256: sha256,
|
||||
bundleSha256: sha256,
|
||||
files: z.array(candidateFileSchema).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export type ReleaseCandidateManifest = z.infer<
|
||||
typeof releaseCandidateManifestSchema
|
||||
>;
|
||||
|
||||
export const RELEASE_CANDIDATE_MANIFEST_PATH =
|
||||
"artifacts/release/release-candidate.json";
|
||||
export const LOCAL_EVIDENCE_ASSESSMENT_PATH =
|
||||
"artifacts/security/local-evidence-assessment.json";
|
||||
|
||||
export const LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS = Object.freeze([
|
||||
"scripts/contracts/release-artifacts.ts",
|
||||
"scripts/create-release-candidate.ts",
|
||||
"scripts/generate-supply-chain.ts",
|
||||
"scripts/lib/build-manifest-outputs.ts",
|
||||
"scripts/lib/json-schema.ts",
|
||||
"scripts/lib/local-policy-evidence.ts",
|
||||
"scripts/lib/local-release-evidence.ts",
|
||||
"scripts/lib/release-candidate.ts",
|
||||
"scripts/lib/release-input-evidence.ts",
|
||||
"scripts/lib/release-runtime-coherence.ts",
|
||||
"scripts/lib/repository-file-inventory.ts",
|
||||
"scripts/lib/secret-scan-evaluator.ts",
|
||||
"scripts/lib/secret-scan-policy.ts",
|
||||
"scripts/lib/secret-scan.ts",
|
||||
"scripts/lib/supply-chain.ts",
|
||||
"scripts/lib/validated-json-artifact.ts",
|
||||
"src/contracts/release-artifacts.ts",
|
||||
"src/features/installed-contract-contributions.ts",
|
||||
"src/features/installed-feature-contracts.ts",
|
||||
] as const);
|
||||
|
||||
export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
|
||||
"config/security/dependency-baseline.approval.json",
|
||||
"config/security/dependency-baseline.json",
|
||||
"config/security/dependency-change-evidence.json",
|
||||
"config/security/dependency-policy.json",
|
||||
"config/security/secret-scan-policy.json",
|
||||
"config/security/vulnerability-exceptions.json",
|
||||
"config/security/vulnerability-policy.json",
|
||||
"schemas/artifacts/build-manifest.schema.json",
|
||||
"schemas/artifacts/dependency-inventory.schema.json",
|
||||
"schemas/artifacts/supply-chain-verification.schema.json",
|
||||
...LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS,
|
||||
] as const);
|
||||
|
||||
export const RELEASE_CANDIDATE_EVIDENCE_PATHS = Object.freeze([
|
||||
"pnpm-lock.yaml",
|
||||
"artifacts/performance/bundle.json",
|
||||
"artifacts/quality/vite-module-inventory.json",
|
||||
"artifacts/release/build-manifest.json",
|
||||
"artifacts/release/checksums.txt",
|
||||
"artifacts/release/dependency-inventory.json",
|
||||
"artifacts/release/provenance.json",
|
||||
"artifacts/release/verification.json",
|
||||
"artifacts/release/sbom.cdx.json",
|
||||
"artifacts/security/dependency-diff.json",
|
||||
"artifacts/security/license-report.json",
|
||||
LOCAL_EVIDENCE_ASSESSMENT_PATH,
|
||||
"artifacts/security/scan.sarif",
|
||||
"artifacts/security/supply-chain-coherence.json",
|
||||
"artifacts/security/supply-chain-verification.json",
|
||||
"artifacts/security/vulnerability-report.json",
|
||||
...LOCAL_EVIDENCE_POLICY_INPUT_PATHS,
|
||||
]);
|
||||
|
||||
export type DistOutput = Readonly<{
|
||||
path: string;
|
||||
bytes: number;
|
||||
gzipBytes: number;
|
||||
sha256: string;
|
||||
}>;
|
||||
|
||||
export async function collectDistOutputs(
|
||||
repositoryRoot = process.cwd(),
|
||||
): Promise<DistOutput[]> {
|
||||
const distRoot = path.resolve(repositoryRoot, "dist");
|
||||
const files = await regularFilesWithin(distRoot);
|
||||
if (files.length === 0) {
|
||||
throw new Error("dist is missing or empty; run the production build first");
|
||||
}
|
||||
return Promise.all(
|
||||
files.map(async (absolutePath) => {
|
||||
const content = await readFile(absolutePath);
|
||||
return Object.freeze({
|
||||
path: path
|
||||
.relative(repositoryRoot, absolutePath)
|
||||
.replaceAll(path.sep, "/"),
|
||||
bytes: content.byteLength,
|
||||
gzipBytes: gzipSync(content).byteLength,
|
||||
sha256: createHash("sha256").update(content).digest("hex"),
|
||||
});
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
export function distSha256(outputs: readonly DistOutput[]): string {
|
||||
return supplyChainDigest(
|
||||
outputs.map(({ path: outputPath, bytes, sha256 }) => ({
|
||||
path: outputPath,
|
||||
bytes,
|
||||
sha256,
|
||||
})),
|
||||
);
|
||||
}
|
||||
|
||||
export async function createReleaseCandidateManifest(
|
||||
repositoryRoot = process.cwd(),
|
||||
): Promise<ReleaseCandidateManifest> {
|
||||
const outputs = await collectDistOutputs(repositoryRoot);
|
||||
const evidence = await Promise.all(
|
||||
RELEASE_CANDIDATE_EVIDENCE_PATHS.map((file) =>
|
||||
digestRequiredFile(repositoryRoot, file),
|
||||
),
|
||||
);
|
||||
const files = [
|
||||
...outputs.map(({ path: outputPath, bytes, sha256 }) => ({
|
||||
path: outputPath,
|
||||
bytes,
|
||||
sha256,
|
||||
})),
|
||||
...evidence,
|
||||
].sort((left, right) => asciiCompare(left.path, right.path));
|
||||
const dependencyInventory = JSON.parse(
|
||||
await readFile(
|
||||
path.resolve(repositoryRoot, "artifacts/release/dependency-inventory.json"),
|
||||
"utf8",
|
||||
),
|
||||
) as { lockfileSha256?: unknown };
|
||||
const rawLockfileSha256 = evidence.find(
|
||||
(file) => file.path === "pnpm-lock.yaml",
|
||||
)?.sha256;
|
||||
if (
|
||||
typeof rawLockfileSha256 !== "string" ||
|
||||
dependencyInventory.lockfileSha256 !== rawLockfileSha256
|
||||
) {
|
||||
throw new Error(
|
||||
"raw pnpm-lock digest mismatch with dependency inventory",
|
||||
);
|
||||
}
|
||||
return releaseCandidateManifestSchema.parse({
|
||||
schemaVersion: 1,
|
||||
distSha256: distSha256(outputs),
|
||||
lockfileSha256: rawLockfileSha256,
|
||||
bundleSha256: supplyChainDigest(files),
|
||||
files,
|
||||
});
|
||||
}
|
||||
|
||||
function asciiCompare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0;
|
||||
}
|
||||
|
||||
export async function verifyReleaseCandidate(
|
||||
value: unknown,
|
||||
repositoryRoot = process.cwd(),
|
||||
): Promise<Readonly<{
|
||||
manifest: ReleaseCandidateManifest | null;
|
||||
currentDistSha256: string | null;
|
||||
failures: readonly string[];
|
||||
}>> {
|
||||
const parsed = releaseCandidateManifestSchema.safeParse(value);
|
||||
if (!parsed.success) {
|
||||
return Object.freeze({
|
||||
manifest: null,
|
||||
currentDistSha256: null,
|
||||
failures: Object.freeze(["release candidate manifest schema mismatch"]),
|
||||
});
|
||||
}
|
||||
const failures: string[] = [];
|
||||
let actual: ReleaseCandidateManifest | null = null;
|
||||
try {
|
||||
actual = await createReleaseCandidateManifest(repositoryRoot);
|
||||
} catch (error) {
|
||||
failures.push(
|
||||
`release candidate inputs unreadable: ${error instanceof Error ? error.message : String(error)}`,
|
||||
);
|
||||
}
|
||||
if (actual) {
|
||||
if (parsed.data.distSha256 !== actual.distSha256) {
|
||||
failures.push("release candidate dist digest mismatch");
|
||||
}
|
||||
if (parsed.data.lockfileSha256 !== actual.lockfileSha256) {
|
||||
failures.push("release candidate lockfile digest mismatch");
|
||||
}
|
||||
if (parsed.data.bundleSha256 !== actual.bundleSha256) {
|
||||
failures.push("release candidate bundle digest mismatch");
|
||||
}
|
||||
if (JSON.stringify(parsed.data.files) !== JSON.stringify(actual.files)) {
|
||||
failures.push("release candidate file set or file digest mismatch");
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
manifest: parsed.data,
|
||||
currentDistSha256: actual?.distSha256 ?? null,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
|
||||
async function digestRequiredFile(repositoryRoot: string, file: string) {
|
||||
const absolutePath = path.resolve(repositoryRoot, file);
|
||||
const relative = path.relative(repositoryRoot, absolutePath);
|
||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
||||
throw new Error(`candidate path escapes repository root: ${file}`);
|
||||
}
|
||||
const metadata = await lstat(absolutePath);
|
||||
if (!metadata.isFile()) {
|
||||
throw new Error(`candidate input is not a regular file: ${file}`);
|
||||
}
|
||||
const content = await readFile(absolutePath);
|
||||
return Object.freeze({
|
||||
path: file,
|
||||
bytes: content.byteLength,
|
||||
sha256: createHash("sha256").update(content).digest("hex"),
|
||||
});
|
||||
}
|
||||
|
||||
async function regularFilesWithin(directory: string): Promise<string[]> {
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
const files: string[] = [];
|
||||
for (const entry of entries.sort((left, right) =>
|
||||
asciiCompare(left.name, right.name),
|
||||
)) {
|
||||
const target = path.join(directory, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
files.push(...(await regularFilesWithin(target)));
|
||||
} else if (entry.isFile()) {
|
||||
files.push(target);
|
||||
} else {
|
||||
throw new Error(`dist contains a non-regular entry: ${target}`);
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { supplyChainDigest } from "./supply-chain.ts";
|
||||
|
||||
export async function digestReleaseInputFiles(
|
||||
files: readonly string[],
|
||||
readBytes: (file: string) => Promise<Buffer> = readFile,
|
||||
): Promise<string> {
|
||||
const rows = await Promise.all(
|
||||
[...files].sort().map(async (file) => ({
|
||||
path: file,
|
||||
sha256: createHash("sha256")
|
||||
.update(await readBytes(file))
|
||||
.digest("hex"),
|
||||
})),
|
||||
);
|
||||
return supplyChainDigest(rows);
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
import { isVersionCompatible } from "../../src/contracts/compatibility.ts";
|
||||
import { verifyContractSet } from "../../src/contracts/contract-set.ts";
|
||||
import type { InstalledContractPackageIdentity } from "../../src/contracts/external-contract-runtime.ts";
|
||||
import type { ReleaseArtifact } from "../../src/contracts/release-artifacts.ts";
|
||||
import { compareReleaseToRuntime } from "../../src/contracts/release-tokens.ts";
|
||||
|
||||
export type ReleaseRuntimeCoherenceInput = Readonly<{
|
||||
release: ReleaseArtifact;
|
||||
runtime: Readonly<{
|
||||
BUILD_ID: string;
|
||||
CONFIG_SCHEMA_VERSION: string;
|
||||
API_CONTRACT_VERSION?: string;
|
||||
RELEASE_ID: string;
|
||||
}>;
|
||||
contractPackages: readonly InstalledContractPackageIdentity[];
|
||||
}>;
|
||||
|
||||
export type ReleaseRuntimeCoherence = Readonly<{
|
||||
compatible: boolean;
|
||||
mismatches: readonly string[];
|
||||
warnings: readonly string[];
|
||||
}>;
|
||||
|
||||
/**
|
||||
* Verifies the runtime identity using the release schema's own contract model.
|
||||
* V1 retains the scalar compatibility policy. V2 has no scalar projection: its
|
||||
* identity is the exact compiled package tuple set and canonical set digest.
|
||||
*/
|
||||
export async function verifyReleaseRuntimeCoherence(
|
||||
input: ReleaseRuntimeCoherenceInput,
|
||||
): Promise<ReleaseRuntimeCoherence> {
|
||||
if (input.release.schemaVersion === 1) {
|
||||
if (input.runtime.API_CONTRACT_VERSION === undefined) {
|
||||
return compareWithoutContractScalar(input, ["apiContractVersion"]);
|
||||
}
|
||||
return compareReleaseToRuntime(input.release, {
|
||||
...input.runtime,
|
||||
API_CONTRACT_VERSION: input.runtime.API_CONTRACT_VERSION,
|
||||
});
|
||||
}
|
||||
|
||||
const comparison = compareWithoutContractScalar(input);
|
||||
const contractSet = await verifyContractSet({
|
||||
expected: input.contractPackages,
|
||||
manifest: input.release.contractSet,
|
||||
});
|
||||
if (contractSet.ok) return comparison;
|
||||
|
||||
const mismatches = Object.freeze([
|
||||
...comparison.mismatches,
|
||||
contractSet.code,
|
||||
]);
|
||||
return Object.freeze({
|
||||
compatible: false,
|
||||
mismatches,
|
||||
warnings: comparison.warnings,
|
||||
});
|
||||
}
|
||||
|
||||
function compareWithoutContractScalar(
|
||||
input: Pick<ReleaseRuntimeCoherenceInput, "release" | "runtime">,
|
||||
initialMismatches: readonly string[] = [],
|
||||
): ReleaseRuntimeCoherence {
|
||||
const mismatches = [...initialMismatches];
|
||||
if (input.release.buildId !== input.runtime.BUILD_ID) {
|
||||
mismatches.push("buildId");
|
||||
}
|
||||
if (
|
||||
!isVersionCompatible(
|
||||
input.release.configSchemaVersion,
|
||||
input.runtime.CONFIG_SCHEMA_VERSION,
|
||||
)
|
||||
) {
|
||||
mismatches.push("configSchemaVersion");
|
||||
}
|
||||
const warnings =
|
||||
input.release.releaseId === input.runtime.RELEASE_ID
|
||||
? []
|
||||
: ["releaseId"];
|
||||
return Object.freeze({
|
||||
compatible: mismatches.length === 0,
|
||||
mismatches: Object.freeze(mismatches),
|
||||
warnings: Object.freeze(warnings),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,392 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import {
|
||||
cp,
|
||||
mkdir,
|
||||
readFile,
|
||||
readdir,
|
||||
rm,
|
||||
stat,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
loadCiGateContract,
|
||||
parseCiGateContract,
|
||||
} from "../contracts/ci-gates.ts";
|
||||
import { linkFixtureNodeModules } from "./fixture-node-modules.ts";
|
||||
import { generateCiWorkflow } from "../generate-ci-workflow.ts";
|
||||
|
||||
export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
|
||||
"src", "tests", "recipes", "scripts", "schemas", "config", "public",
|
||||
".gitea", ".storybook", "index.html", "package.json", "tsconfig.base.json",
|
||||
"tsconfig.json", "tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json",
|
||||
"tsconfig.recipes.json", "tsconfig.web-worker.json", "tsconfig.service-worker.json",
|
||||
"vite.service-worker.config.ts", "vite.config.ts", "vitest.config.ts",
|
||||
"playwright.config.ts", "playwright.capabilities.config.ts", "playwright.dev.config.ts",
|
||||
"playwright.storybook.config.ts", "playwright.visual.config.ts", "eslint.config.ts",
|
||||
".dependency-cruiser.json", ".nvmrc", ".gitignore",
|
||||
// Install and workspace identity. Without these the fixture is not the same
|
||||
// project: `corepack pnpm` resolves a different store, and the provider
|
||||
// suites — which build a release candidate containing `pnpm-lock.yaml` —
|
||||
// cannot assemble their fixture at all.
|
||||
".npmrc", "pnpm-lock.yaml", "pnpm-workspace.yaml",
|
||||
] as const);
|
||||
|
||||
/**
|
||||
* This is the only copy-target list. Each removal script used to keep its own,
|
||||
* and they drifted: the reference-feature fixture omitted
|
||||
* `playwright.capabilities.config.ts`, which the repository file inventory
|
||||
* requires, so supply-chain generation failed inside the fixture and took every
|
||||
* provider suite down with it — twenty-odd failures with one cause.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Regenerated result trees under `artifacts/`: traces, coverage HTML, recorded
|
||||
* videos and Storybook bundles. They are tens of megabytes and mean nothing to
|
||||
* a fixture. Everything else under `artifacts/` is release evidence a candidate
|
||||
* is assembled from — and most of it is git-ignored too, so "is it tracked?"
|
||||
* cannot be used to tell the two apart. `keepsReleaseEvidence` in
|
||||
* tests/unit/removal-fixture.test.ts pins both halves of this split.
|
||||
*/
|
||||
const REGENERATED_ARTIFACT_TREES: readonly string[] = Object.freeze([
|
||||
"artifacts/storybook",
|
||||
"artifacts/tests/browser-capabilities",
|
||||
"artifacts/tests/coverage",
|
||||
"artifacts/tests/e2e",
|
||||
"artifacts/tests/storybook",
|
||||
"artifacts/tests/visual",
|
||||
]);
|
||||
|
||||
/**
|
||||
* Copies the release evidence a candidate build needs into a fixture root.
|
||||
*
|
||||
* A fixture that omits it cannot assemble a candidate archive at all, so every
|
||||
* provider suite fails while constructing its own fixture — long before it
|
||||
* reaches an assertion, and with an error that says nothing about the
|
||||
* capability under test.
|
||||
*/
|
||||
export async function copyReleaseEvidenceTree(
|
||||
sourceRoot: string,
|
||||
destinationRoot: string,
|
||||
): Promise<void> {
|
||||
const source = path.join(sourceRoot, "artifacts");
|
||||
try {
|
||||
await stat(source);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
await cp(source, path.join(destinationRoot, "artifacts"), {
|
||||
recursive: true,
|
||||
filter: (candidate) => {
|
||||
const relative = path.relative(sourceRoot, candidate).split(path.sep).join("/");
|
||||
return !REGENERATED_ARTIFACT_TREES.some(
|
||||
(tree) => relative === tree || relative.startsWith(`${tree}/`),
|
||||
);
|
||||
},
|
||||
});
|
||||
// The result directories still have to exist: several are tracked through a
|
||||
// `.gitkeep` the repository inventory expects to find.
|
||||
for (const tree of REGENERATED_ARTIFACT_TREES) {
|
||||
await mkdir(path.join(destinationRoot, tree), { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
export const RELEASE_EVIDENCE_REGENERATED_TREES = REGENERATED_ARTIFACT_TREES;
|
||||
|
||||
export function requireRemovalFixtureEnvironment(name: string): string {
|
||||
const value = process.env[name];
|
||||
if (!value) throw new Error(`${name} is required for removal verification`);
|
||||
return value;
|
||||
}
|
||||
|
||||
export async function prepareRemovalFixture(
|
||||
root: string,
|
||||
copyTargets: readonly string[] = REMOVAL_FIXTURE_COPY_TARGETS,
|
||||
): Promise<void> {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
await mkdir(root, { recursive: true });
|
||||
for (const target of copyTargets) {
|
||||
await cp(target, path.join(root, target), { recursive: true });
|
||||
}
|
||||
await copyReleaseEvidenceTree(process.cwd(), root);
|
||||
runFixtureGit(root, ["init", "--quiet", "--initial-branch=fixture"]);
|
||||
await linkFixtureNodeModules(root);
|
||||
}
|
||||
|
||||
/**
|
||||
* Records the fixture's post-removal contents as its repository state.
|
||||
*
|
||||
* The release candidate path asks `git ls-files` what the repository contains —
|
||||
* the supply-chain inventory is defined as the tracked file set, not as
|
||||
* whatever happens to be on disk. A fixture without a repository cannot answer
|
||||
* that, so supply-chain generation failed and took every provider suite down
|
||||
* with it; the claim "this build still produces a release candidate after the
|
||||
* capability is removed" was never actually being tested.
|
||||
*
|
||||
* It runs after the removal, not during preparation: an index recorded before
|
||||
* the deletions still lists the removed files, and the inventory then demands
|
||||
* files the fixture exists to prove are gone.
|
||||
*/
|
||||
export function sealRemovalFixtureRepository(root: string): void {
|
||||
// `.gitignore` travels with the fixture, so the tracked set it records is the
|
||||
// same tracked set the real repository has. Without it every generated
|
||||
// artifact and every linked module landed in the index, and the supply-chain
|
||||
// inventory refused the fixture for having tracked and generated paths
|
||||
// collide — the fixture disagreed with the repository it was copied from.
|
||||
runFixtureGit(root, ["add", "--all"]);
|
||||
runFixtureGit(root, ["commit", "--quiet", "--no-gpg-sign", "-m", "removal fixture"]);
|
||||
}
|
||||
|
||||
function runFixtureGit(root: string, argv: readonly string[]): void {
|
||||
const result = spawnSync("git", [...argv], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
env: {
|
||||
...process.env,
|
||||
GIT_AUTHOR_NAME: "removal-fixture",
|
||||
GIT_AUTHOR_EMAIL: "removal-fixture@localhost",
|
||||
GIT_COMMITTER_NAME: "removal-fixture",
|
||||
GIT_COMMITTER_EMAIL: "removal-fixture@localhost",
|
||||
},
|
||||
});
|
||||
if (result.error || result.status !== 0) {
|
||||
throw new Error(
|
||||
`removal fixture repository setup failed at git ${argv[0]}: ${
|
||||
result.stderr || result.error?.message || `exit ${result.status}`
|
||||
}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export function runRemovalFixturePnpm(
|
||||
root: string,
|
||||
pnpmCli: string,
|
||||
script: string,
|
||||
extra: readonly string[] = [],
|
||||
): boolean {
|
||||
return spawnSync(process.execPath, [pnpmCli, script, ...extra], {
|
||||
cwd: root,
|
||||
stdio: "inherit",
|
||||
env: { ...process.env, CI_CONTRACT_MODE: "removal-fixture" },
|
||||
}).status === 0;
|
||||
}
|
||||
|
||||
export async function filesBelow(directory: string): Promise<string[]> {
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
return (await Promise.all(entries.map((entry) => {
|
||||
const target = path.join(directory, entry.name);
|
||||
return entry.isDirectory() ? filesBelow(target) : [target];
|
||||
}))).flat();
|
||||
}
|
||||
|
||||
function isWithin(target: string, root: string): boolean {
|
||||
const relative = path.relative(root, target);
|
||||
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
|
||||
}
|
||||
|
||||
export async function runtimeImportGraph(
|
||||
root: string,
|
||||
runtimeSourceRoots: readonly string[],
|
||||
): Promise<Readonly<{ dependentTests: readonly string[]; importingFiles: readonly string[] }>> {
|
||||
const files = (await filesBelow(root))
|
||||
.filter((file) => /\.(?:[cm]?ts|tsx)$/u.test(file))
|
||||
.map((file) => path.resolve(file));
|
||||
if (files.length === 0) {
|
||||
throw new Error("removal fixture scanned module universe is empty");
|
||||
}
|
||||
const sourceSet = new Set(files);
|
||||
const runtimeRoots = runtimeSourceRoots.map((entry) => path.resolve(root, entry));
|
||||
const imports = new Map<string, readonly string[]>();
|
||||
for (const file of files) {
|
||||
const source = await readFile(file, "utf8");
|
||||
const specifiers = [...source.matchAll(/(?:from\s*|import\s*\(\s*|import\s*)["']([^"']+)["']/gu)]
|
||||
.map((match) => match[1])
|
||||
.filter((specifier): specifier is string => typeof specifier === "string" && specifier.startsWith("."));
|
||||
imports.set(file, specifiers.map((specifier) => {
|
||||
const base = path.resolve(path.dirname(file), specifier);
|
||||
return [base, `${base}.ts`, `${base}.tsx`, `${base}.mts`, `${base}.cts`, path.join(base, "index.ts"), path.join(base, "index.tsx")]
|
||||
.find((candidate) => sourceSet.has(candidate)) ?? base;
|
||||
}));
|
||||
}
|
||||
const memo = new Map<string, boolean>();
|
||||
const reachesRuntime = (file: string, visiting = new Set<string>()): boolean => {
|
||||
if (runtimeRoots.some((runtimeRoot) => isWithin(file, runtimeRoot))) return true;
|
||||
const known = memo.get(file);
|
||||
if (known !== undefined) return known;
|
||||
if (visiting.has(file)) return false;
|
||||
visiting.add(file);
|
||||
const reaches = (imports.get(file) ?? []).some((dependency) =>
|
||||
runtimeRoots.some((runtimeRoot) => isWithin(dependency, runtimeRoot)) ||
|
||||
(sourceSet.has(dependency) && reachesRuntime(dependency, visiting))
|
||||
);
|
||||
visiting.delete(file);
|
||||
memo.set(file, reaches);
|
||||
return reaches;
|
||||
};
|
||||
const testsRoot = path.resolve(root, "tests");
|
||||
return Object.freeze({
|
||||
dependentTests: Object.freeze(files.filter((file) => isWithin(file, testsRoot) && reachesRuntime(file))),
|
||||
importingFiles: Object.freeze(files.filter((file) =>
|
||||
!runtimeRoots.some((runtimeRoot) => isWithin(file, runtimeRoot)) &&
|
||||
(imports.get(file) ?? []).some((dependency) =>
|
||||
runtimeRoots.some((runtimeRoot) => isWithin(dependency, runtimeRoot))
|
||||
)
|
||||
)),
|
||||
});
|
||||
}
|
||||
|
||||
export async function removeRuntimeDependentTests(
|
||||
root: string,
|
||||
runtimeSourceRoots: readonly string[],
|
||||
): Promise<number> {
|
||||
const graph = await runtimeImportGraph(root, runtimeSourceRoots);
|
||||
if (graph.dependentTests.length === 0) {
|
||||
throw new Error("removal fixture: no runtime-dependent tests discovered");
|
||||
}
|
||||
await Promise.all(graph.dependentTests.map((file) => rm(file, { force: true })));
|
||||
return graph.dependentTests.length;
|
||||
}
|
||||
|
||||
export async function assertNoRuntimeImports(
|
||||
root: string,
|
||||
runtimeSourceRoots: readonly string[],
|
||||
capability: string,
|
||||
): Promise<void> {
|
||||
const graph = await runtimeImportGraph(root, runtimeSourceRoots);
|
||||
if (graph.importingFiles.length > 0) {
|
||||
throw new Error(`Removed ${capability} runtime is still imported by: ${graph.importingFiles.map((file) => path.relative(root, file)).join(", ")}`);
|
||||
}
|
||||
}
|
||||
|
||||
export function pruneScriptOrchestration(
|
||||
scripts: Record<string, string>,
|
||||
orchestrationScript: string,
|
||||
removedScripts: ReadonlySet<string>,
|
||||
): void {
|
||||
const command = scripts[orchestrationScript];
|
||||
if (!command) return;
|
||||
scripts[orchestrationScript] = command.split(" && ").filter((segment) =>
|
||||
![...removedScripts].some((removed) =>
|
||||
new RegExp(`(?:^|\\s)(?:corepack\\s+)?pnpm\\s+${removed.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}(?:\\s|$)`, "u").test(segment)
|
||||
)
|
||||
).join(" && ");
|
||||
}
|
||||
|
||||
export async function regenerateRemovalFixtureWorkflow(root: string): Promise<void> {
|
||||
const contract = await loadCiGateContract(root, { mode: "removal-fixture" });
|
||||
await generateCiWorkflow({ root, contract, check: false });
|
||||
// Every removal script calls this once, after it has finished mutating the
|
||||
// tree, so it is the one place where the fixture's contents are final.
|
||||
await pruneRemovalFixtureInventoryRoots(root);
|
||||
sealRemovalFixtureRepository(root);
|
||||
}
|
||||
|
||||
/**
|
||||
* Drops repository roots the removal deleted from the supply-chain inventory
|
||||
* policy.
|
||||
*
|
||||
* The policy lists `recipes` as a required tracked root, and removing an
|
||||
* optional recipe deletes exactly that directory. Supply-chain generation then
|
||||
* refused the fixture for missing a root the removal was supposed to remove, so
|
||||
* the capability could never be shown to be removable. A root that is not on
|
||||
* disk after the removal is not required of the result.
|
||||
*/
|
||||
async function pruneRemovalFixtureInventoryRoots(root: string): Promise<void> {
|
||||
const policyPath = path.join(root, "config/security/secret-scan-policy.json");
|
||||
let policy: Record<string, unknown>;
|
||||
try {
|
||||
policy = JSON.parse(await readFile(policyPath, "utf8")) as Record<string, unknown>;
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
const tracked = policy["trackedRoots"];
|
||||
if (!Array.isArray(tracked)) return;
|
||||
const surviving: string[] = [];
|
||||
for (const entry of tracked) {
|
||||
if (typeof entry !== "string") continue;
|
||||
try {
|
||||
await stat(path.join(root, entry));
|
||||
surviving.push(entry);
|
||||
} catch {
|
||||
// Deleted by the removal under test.
|
||||
}
|
||||
}
|
||||
if (surviving.length === tracked.length) return;
|
||||
policy["trackedRoots"] = surviving;
|
||||
await writeFile(policyPath, `${JSON.stringify(policy, null, 2)}\n`, "utf8");
|
||||
}
|
||||
|
||||
export async function pruneRemovalFixtureCiContract(options: Readonly<{
|
||||
root: string;
|
||||
removedScripts: ReadonlySet<string>;
|
||||
removedEvidencePathFragments: readonly string[];
|
||||
}>): Promise<void> {
|
||||
const packagePath = path.join(options.root, "package.json");
|
||||
const gatesPath = path.join(options.root, "config/ci/gates.json");
|
||||
const packageDocument = JSON.parse(await readFile(packagePath, "utf8")) as {
|
||||
scripts: Record<string, string>;
|
||||
};
|
||||
for (const script of options.removedScripts) delete packageDocument.scripts[script];
|
||||
packageDocument.scripts["check:ci-workflow"] =
|
||||
"node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture";
|
||||
packageDocument.scripts["check:ci"] =
|
||||
"corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts --reduced-removal-fixture && corepack pnpm check:ci-workflow";
|
||||
|
||||
const contract = structuredClone(
|
||||
parseCiGateContract(JSON.parse(await readFile(gatesPath, "utf8"))),
|
||||
);
|
||||
const removedCommandIds = new Set(
|
||||
contract.commands
|
||||
.filter(({ script }) => options.removedScripts.has(script))
|
||||
.map(({ id }) => id),
|
||||
);
|
||||
const missing = [...options.removedScripts].filter(
|
||||
(script) => !contract.commands.some((command) => command.script === script),
|
||||
);
|
||||
if (missing.length > 0) {
|
||||
throw new Error(`removal fixture CI command set is incomplete: ${missing.join(", ")}`);
|
||||
}
|
||||
const removedArtifactIds = new Set(
|
||||
contract.artifacts
|
||||
.filter(({ path: artifactPath }) =>
|
||||
options.removedEvidencePathFragments.some((fragment) => artifactPath.includes(fragment))
|
||||
)
|
||||
.map(({ id }) => id),
|
||||
);
|
||||
for (const fragment of options.removedEvidencePathFragments) {
|
||||
if (!contract.artifacts.some(({ path: artifactPath }) => artifactPath.includes(fragment))) {
|
||||
throw new Error(`removal fixture CI evidence is missing: ${fragment}`);
|
||||
}
|
||||
}
|
||||
contract.commands = contract.commands.filter(({ id }) => !removedCommandIds.has(id));
|
||||
contract.artifacts = contract.artifacts
|
||||
.filter(({ id }) => !removedArtifactIds.has(id))
|
||||
.map((artifact) => artifact.production === "command-generated"
|
||||
? {
|
||||
...artifact,
|
||||
producerCommandIds: artifact.producerCommandIds.filter(
|
||||
(commandId) => !removedCommandIds.has(commandId),
|
||||
),
|
||||
}
|
||||
: artifact)
|
||||
.filter((artifact) =>
|
||||
artifact.production !== "command-generated" || artifact.producerCommandIds.length > 0
|
||||
);
|
||||
const retainedArtifactIds = new Set(contract.artifacts.map(({ id }) => id));
|
||||
for (const gate of contract.gates) {
|
||||
gate.commandIds = gate.commandIds.filter((commandId) => !removedCommandIds.has(commandId));
|
||||
gate.evidenceArtifactIds = gate.evidenceArtifactIds.filter((artifactId) =>
|
||||
retainedArtifactIds.has(artifactId)
|
||||
);
|
||||
}
|
||||
const referencedSchemaIds = new Set(contract.artifacts.map(({ schemaId }) => schemaId));
|
||||
contract.artifactSchemas = contract.artifactSchemas.filter(({ id }) =>
|
||||
referencedSchemaIds.has(id)
|
||||
);
|
||||
const validated = parseCiGateContract(contract, { mode: "removal-fixture" });
|
||||
await Promise.all([
|
||||
writeFile(packagePath, `${JSON.stringify(packageDocument, null, 2)}\n`),
|
||||
writeFile(gatesPath, `${JSON.stringify(validated, null, 2)}\n`),
|
||||
]);
|
||||
}
|
||||
@@ -0,0 +1,327 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import {
|
||||
lstat,
|
||||
open,
|
||||
readdir,
|
||||
realpath,
|
||||
} from "node:fs/promises";
|
||||
import type { Stats } from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
export type GitFileListResult = Readonly<{
|
||||
error?: Error;
|
||||
status: number | null;
|
||||
signal: NodeJS.Signals | null;
|
||||
stdout: Buffer;
|
||||
stderr: Buffer;
|
||||
}>;
|
||||
|
||||
export type RepositoryFileInventory = Readonly<{
|
||||
trackedFiles: readonly string[];
|
||||
generatedFiles: readonly string[];
|
||||
files: readonly string[];
|
||||
}>;
|
||||
|
||||
export type RepositoryFileInventoryPolicy = Readonly<{
|
||||
trackedRoots: readonly string[];
|
||||
generatedRoots: readonly string[];
|
||||
optionalRoots: readonly string[];
|
||||
}>;
|
||||
|
||||
type InventoryOptions = Readonly<{
|
||||
repositoryRoot?: string;
|
||||
trackedRoots: readonly string[];
|
||||
generatedRoots?: readonly string[];
|
||||
optionalRoots?: readonly string[];
|
||||
runGit?: (repositoryRoot: string) => GitFileListResult;
|
||||
lstatPath?: (target: string) => Promise<Stats>;
|
||||
realpathPath?: (target: string) => Promise<string>;
|
||||
assertReadable?: (target: string) => Promise<void>;
|
||||
}>;
|
||||
|
||||
const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function requiredStringArray(
|
||||
value: unknown,
|
||||
label: string,
|
||||
options: Readonly<{ allowEmpty: boolean }>,
|
||||
): readonly string[] {
|
||||
if (
|
||||
!Array.isArray(value) ||
|
||||
(!options.allowEmpty && value.length === 0) ||
|
||||
value.some((entry) => typeof entry !== "string" || entry.length === 0)
|
||||
) {
|
||||
throw new TypeError(`${label} must be an array of non-empty strings`);
|
||||
}
|
||||
if (new Set(value).size !== value.length) {
|
||||
throw new TypeError(`${label} must not contain duplicate roots`);
|
||||
}
|
||||
return Object.freeze([...value] as string[]);
|
||||
}
|
||||
|
||||
export function parseRepositoryFileInventoryPolicy(
|
||||
value: unknown,
|
||||
): RepositoryFileInventoryPolicy {
|
||||
if (!isRecord(value)) {
|
||||
throw new TypeError("repository inventory policy must be an object");
|
||||
}
|
||||
return Object.freeze({
|
||||
trackedRoots: requiredStringArray(value.trackedRoots, "trackedRoots", {
|
||||
allowEmpty: false,
|
||||
}),
|
||||
generatedRoots: requiredStringArray(
|
||||
value.generatedRoots,
|
||||
"generatedRoots",
|
||||
{ allowEmpty: true },
|
||||
),
|
||||
optionalRoots:
|
||||
value.optionalRoots === undefined
|
||||
? Object.freeze([])
|
||||
: requiredStringArray(value.optionalRoots, "optionalRoots", {
|
||||
allowEmpty: true,
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
function defaultGitFileList(repositoryRoot: string): GitFileListResult {
|
||||
const result = spawnSync("git", ["ls-files", "-z"], {
|
||||
cwd: repositoryRoot,
|
||||
encoding: "buffer",
|
||||
maxBuffer: 64 * 1024 * 1024,
|
||||
});
|
||||
return {
|
||||
...(result.error ? { error: result.error } : {}),
|
||||
status: result.status,
|
||||
signal: result.signal,
|
||||
stdout: result.stdout ?? Buffer.alloc(0),
|
||||
stderr: result.stderr ?? Buffer.alloc(0),
|
||||
};
|
||||
}
|
||||
|
||||
async function defaultAssertReadable(target: string): Promise<void> {
|
||||
const handle = await open(target, "r");
|
||||
await handle.close();
|
||||
}
|
||||
|
||||
export function normalizeRepositoryRelativePath(
|
||||
value: string,
|
||||
label = "repository path",
|
||||
): string {
|
||||
if (
|
||||
value.length === 0 ||
|
||||
path.posix.isAbsolute(value) ||
|
||||
path.win32.isAbsolute(value) ||
|
||||
value.includes("\\") ||
|
||||
value.includes("\0") ||
|
||||
value.endsWith("/")
|
||||
) {
|
||||
throw new TypeError(`${label} must be a repository-relative POSIX path`);
|
||||
}
|
||||
const normalized = path.posix.normalize(value);
|
||||
if (
|
||||
normalized === "." ||
|
||||
normalized === ".." ||
|
||||
normalized.startsWith("../") ||
|
||||
normalized !== value
|
||||
) {
|
||||
throw new TypeError(`${label} must be a repository-relative POSIX path`);
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function isWithinRoot(root: string, target: string): boolean {
|
||||
const relative = path.relative(root, target);
|
||||
return (
|
||||
relative === "" ||
|
||||
(relative !== ".." &&
|
||||
!relative.startsWith(`..${path.sep}`) &&
|
||||
!path.isAbsolute(relative))
|
||||
);
|
||||
}
|
||||
|
||||
function parseGitFileList(result: GitFileListResult): string[] {
|
||||
if (
|
||||
result.error ||
|
||||
result.status !== 0 ||
|
||||
result.signal !== null ||
|
||||
result.stderr.byteLength > 0
|
||||
) {
|
||||
const detail = result.error?.message ?? result.stderr.toString("utf8").trim();
|
||||
throw new Error(
|
||||
`git ls-files failed${result.signal ? ` (${result.signal})` : ""}${detail ? `: ${detail}` : ""}`,
|
||||
);
|
||||
}
|
||||
if (result.stdout.byteLength === 0) return [];
|
||||
if (result.stdout.at(-1) !== 0) {
|
||||
throw new TypeError("git ls-files returned output without a terminal NUL");
|
||||
}
|
||||
let decoded: string;
|
||||
try {
|
||||
decoded = utf8Decoder.decode(result.stdout);
|
||||
} catch (error) {
|
||||
throw new TypeError("git ls-files returned malformed UTF-8", {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
const rows = decoded.slice(0, -1).split("\0");
|
||||
if (rows.some((row) => row.length === 0)) {
|
||||
throw new TypeError("git ls-files returned an empty NUL-delimited path");
|
||||
}
|
||||
const normalized = rows.map((row) =>
|
||||
normalizeRepositoryRelativePath(row, "git ls-files path"),
|
||||
);
|
||||
if (new Set(normalized).size !== normalized.length) {
|
||||
throw new TypeError("git ls-files returned a duplicate path");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
"code" in error &&
|
||||
error.code === code
|
||||
);
|
||||
}
|
||||
|
||||
export async function buildRepositoryFileInventory(
|
||||
options: InventoryOptions,
|
||||
): Promise<RepositoryFileInventory> {
|
||||
const repositoryRoot = path.resolve(options.repositoryRoot ?? process.cwd());
|
||||
const lstatPath = options.lstatPath ?? lstat;
|
||||
const realpathPath = options.realpathPath ?? realpath;
|
||||
const assertReadable = options.assertReadable ?? defaultAssertReadable;
|
||||
const trackedRoots = options.trackedRoots.map((root) =>
|
||||
normalizeRepositoryRelativePath(root, "tracked root"),
|
||||
);
|
||||
const generatedRoots = (options.generatedRoots ?? []).map((root) =>
|
||||
normalizeRepositoryRelativePath(root, "generated root"),
|
||||
);
|
||||
const optionalRoots = new Set(
|
||||
(options.optionalRoots ?? []).map((root) =>
|
||||
normalizeRepositoryRelativePath(root, "optional root"),
|
||||
),
|
||||
);
|
||||
for (const root of optionalRoots) {
|
||||
if (!generatedRoots.includes(root)) {
|
||||
throw new TypeError(`optional root is not generated: ${root}`);
|
||||
}
|
||||
}
|
||||
|
||||
const resolvedRepositoryRoot = await realpathPath(repositoryRoot);
|
||||
|
||||
async function validateRegularFile(relativePath: string): Promise<void> {
|
||||
const absolutePath = path.resolve(repositoryRoot, relativePath);
|
||||
if (!isWithinRoot(repositoryRoot, absolutePath)) {
|
||||
throw new TypeError(`repository inventory path escapes root: ${relativePath}`);
|
||||
}
|
||||
const metadata = await lstatPath(absolutePath);
|
||||
if (!metadata.isFile() || metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`repository inventory path is not a regular file: ${relativePath}`);
|
||||
}
|
||||
const resolvedPath = await realpathPath(absolutePath);
|
||||
if (!isWithinRoot(resolvedRepositoryRoot, resolvedPath)) {
|
||||
throw new TypeError(`repository inventory symlink escapes root: ${relativePath}`);
|
||||
}
|
||||
try {
|
||||
await assertReadable(absolutePath);
|
||||
} catch (error) {
|
||||
throw new Error(`repository inventory file is unreadable: ${relativePath}`, {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function validateRoot(
|
||||
relativeRoot: string,
|
||||
optional: boolean,
|
||||
): Promise<Stats | null> {
|
||||
const absoluteRoot = path.resolve(repositoryRoot, relativeRoot);
|
||||
try {
|
||||
const metadata = await lstatPath(absoluteRoot);
|
||||
const resolvedRoot = await realpathPath(absoluteRoot);
|
||||
if (!isWithinRoot(resolvedRepositoryRoot, resolvedRoot)) {
|
||||
throw new TypeError(`repository root escapes repository: ${relativeRoot}`);
|
||||
}
|
||||
if (metadata.isSymbolicLink() || (!metadata.isFile() && !metadata.isDirectory())) {
|
||||
throw new TypeError(`repository root is not a regular file or directory: ${relativeRoot}`);
|
||||
}
|
||||
return metadata;
|
||||
} catch (error) {
|
||||
if (optional && hasErrorCode(error, "ENOENT")) return null;
|
||||
throw new Error(`required repository root is unavailable: ${relativeRoot}`, {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for (const root of trackedRoots) {
|
||||
await validateRoot(root, false);
|
||||
}
|
||||
|
||||
const trackedFiles = parseGitFileList(
|
||||
(options.runGit ?? defaultGitFileList)(repositoryRoot),
|
||||
).sort();
|
||||
for (const root of trackedRoots) {
|
||||
if (!trackedFiles.some((file) => file === root || file.startsWith(`${root}/`))) {
|
||||
throw new Error(`required tracked file inventory is empty: ${root}`);
|
||||
}
|
||||
}
|
||||
for (const file of trackedFiles) {
|
||||
await validateRegularFile(file);
|
||||
}
|
||||
|
||||
const generatedFiles: string[] = [];
|
||||
async function collectGenerated(relativeTarget: string): Promise<void> {
|
||||
const absoluteTarget = path.resolve(repositoryRoot, relativeTarget);
|
||||
const metadata = await lstatPath(absoluteTarget);
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`generated inventory path is a symlink: ${relativeTarget}`);
|
||||
}
|
||||
if (metadata.isFile()) {
|
||||
await validateRegularFile(relativeTarget);
|
||||
generatedFiles.push(relativeTarget);
|
||||
return;
|
||||
}
|
||||
if (!metadata.isDirectory()) {
|
||||
throw new TypeError(`generated inventory path is not regular: ${relativeTarget}`);
|
||||
}
|
||||
const entries = await readdir(absoluteTarget, { withFileTypes: true });
|
||||
for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
|
||||
await collectGenerated(
|
||||
normalizeRepositoryRelativePath(
|
||||
`${relativeTarget}/${entry.name}`,
|
||||
"generated inventory path",
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const root of generatedRoots) {
|
||||
const metadata = await validateRoot(root, optionalRoots.has(root));
|
||||
if (metadata) await collectGenerated(root);
|
||||
}
|
||||
|
||||
if (new Set(generatedFiles).size !== generatedFiles.length) {
|
||||
throw new TypeError("generated inventory contains duplicate paths");
|
||||
}
|
||||
const uniqueTracked = [...trackedFiles].sort();
|
||||
const uniqueGenerated = [...generatedFiles].sort();
|
||||
const trackedSet = new Set(uniqueTracked);
|
||||
const collisions = uniqueGenerated.filter((file) => trackedSet.has(file));
|
||||
if (collisions.length > 0) {
|
||||
throw new TypeError(
|
||||
`tracked and generated inventory paths collide: ${collisions.join(", ")}`,
|
||||
);
|
||||
}
|
||||
return Object.freeze({
|
||||
trackedFiles: Object.freeze(uniqueTracked),
|
||||
generatedFiles: Object.freeze(uniqueGenerated),
|
||||
files: Object.freeze([...uniqueTracked, ...uniqueGenerated].sort()),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,346 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import {
|
||||
lstat,
|
||||
mkdir,
|
||||
open,
|
||||
realpath,
|
||||
rename,
|
||||
rm,
|
||||
} from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
|
||||
type WritableHandle = Readonly<{
|
||||
writeFile(data: string): Promise<unknown>;
|
||||
sync(): Promise<unknown>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
|
||||
type DirectoryHandle = Readonly<{
|
||||
sync(): Promise<unknown>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
|
||||
export type RiskCoverageArtifactFileSystem = Readonly<{
|
||||
openFile(target: string, flags: number, mode: number): Promise<WritableHandle>;
|
||||
openDirectory(target: string): Promise<DirectoryHandle>;
|
||||
rename(source: string, destination: string): Promise<unknown>;
|
||||
rm(target: string, options: Readonly<{ force: true }>): Promise<unknown>;
|
||||
}>;
|
||||
|
||||
type WriterDependencies = Readonly<{
|
||||
createNonce?: () => string;
|
||||
fileSystem?: RiskCoverageArtifactFileSystem;
|
||||
}>;
|
||||
|
||||
type ReadableHandle = Readonly<{
|
||||
stat(): Promise<Stats>;
|
||||
readFile(encoding: "utf8"): Promise<string>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
|
||||
type InputDependencies = Readonly<{
|
||||
lstatPath?: (target: string) => Promise<Stats>;
|
||||
realpathPath?: (target: string) => Promise<string>;
|
||||
openFile?: (target: string, flags: number) => Promise<ReadableHandle>;
|
||||
}>;
|
||||
|
||||
const defaultFileSystem: RiskCoverageArtifactFileSystem = Object.freeze({
|
||||
openFile: async (target, flags, mode) => {
|
||||
const handle = await open(target, flags, mode);
|
||||
return {
|
||||
writeFile: async (data) => handle.writeFile(data, "utf8"),
|
||||
sync: async () => handle.sync(),
|
||||
close: async () => handle.close(),
|
||||
};
|
||||
},
|
||||
openDirectory: async (target) => {
|
||||
const handle = await open(target, constants.O_RDONLY);
|
||||
return {
|
||||
sync: async () => handle.sync(),
|
||||
close: async () => handle.close(),
|
||||
};
|
||||
},
|
||||
rename,
|
||||
rm,
|
||||
});
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
"code" in error &&
|
||||
error.code === code
|
||||
);
|
||||
}
|
||||
|
||||
function isWithin(root: string, target: string): boolean {
|
||||
const relative = path.relative(root, target);
|
||||
return (
|
||||
relative === "" ||
|
||||
(relative !== ".." &&
|
||||
!relative.startsWith(`..${path.sep}`) &&
|
||||
!path.isAbsolute(relative))
|
||||
);
|
||||
}
|
||||
|
||||
function hasStableIdentity(metadata: Stats): boolean {
|
||||
return (
|
||||
Number.isSafeInteger(metadata.dev) &&
|
||||
Number.isSafeInteger(metadata.ino) &&
|
||||
metadata.dev > 0 &&
|
||||
metadata.ino > 0
|
||||
);
|
||||
}
|
||||
|
||||
function sameFileIdentity(before: Stats, after: Stats): boolean {
|
||||
if (!hasStableIdentity(before) || !hasStableIdentity(after)) {
|
||||
throw new TypeError("stable file identity unavailable");
|
||||
}
|
||||
return before.dev === after.dev && before.ino === after.ino;
|
||||
}
|
||||
|
||||
async function rejectSymlinkAncestors(
|
||||
repositoryRoot: string,
|
||||
relativePath: string,
|
||||
label: string,
|
||||
lstatPath: (target: string) => Promise<Stats>,
|
||||
): Promise<void> {
|
||||
let current = repositoryRoot;
|
||||
let currentRelative = "";
|
||||
const directory = path.posix.dirname(relativePath);
|
||||
if (directory === ".") return;
|
||||
for (const segment of directory.split("/")) {
|
||||
current = path.join(current, segment);
|
||||
currentRelative = currentRelative ? `${currentRelative}/${segment}` : segment;
|
||||
const metadata = await lstatPath(current);
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`${label} ancestor is a symlink: ${currentRelative}`);
|
||||
}
|
||||
if (!metadata.isDirectory()) {
|
||||
throw new TypeError(`${label} ancestor is not a directory: ${currentRelative}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function assertDirectory(metadata: Stats, relativePath: string): void {
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`artifact ancestor is a symlink: ${relativePath}`);
|
||||
}
|
||||
if (!metadata.isDirectory()) {
|
||||
throw new TypeError(`artifact ancestor is not a directory: ${relativePath}`);
|
||||
}
|
||||
}
|
||||
|
||||
export async function readRiskCoverageInput(input: Readonly<{
|
||||
repositoryRoot: string;
|
||||
relativePath: string;
|
||||
label: string;
|
||||
}>, dependencies: InputDependencies = {}): Promise<Readonly<{
|
||||
relativePath: string;
|
||||
absolutePath: string;
|
||||
text: string;
|
||||
}>> {
|
||||
const lstatPath = dependencies.lstatPath ?? lstat;
|
||||
const realpathPath = dependencies.realpathPath ?? realpath;
|
||||
const openFile = dependencies.openFile ??
|
||||
((target: string, flags: number) => open(target, flags));
|
||||
const relativePath = normalizeRepositoryRelativePath(
|
||||
input.relativePath,
|
||||
`${input.label} path`,
|
||||
);
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot);
|
||||
const repositoryRealpath = await realpathPath(repositoryRoot);
|
||||
const absolutePath = path.resolve(repositoryRoot, relativePath);
|
||||
await rejectSymlinkAncestors(
|
||||
repositoryRoot,
|
||||
relativePath,
|
||||
input.label,
|
||||
lstatPath,
|
||||
);
|
||||
const metadata = await lstatPath(absolutePath);
|
||||
if (metadata.isSymbolicLink()) {
|
||||
throw new TypeError(`${input.label} path is a symlink: ${relativePath}`);
|
||||
}
|
||||
if (!metadata.isFile()) {
|
||||
throw new TypeError(`${input.label} path is not a regular file: ${relativePath}`);
|
||||
}
|
||||
const resolvedPath = await realpathPath(absolutePath);
|
||||
if (!isWithin(repositoryRealpath, resolvedPath)) {
|
||||
throw new TypeError(`${input.label} path is outside repository: ${relativePath}`);
|
||||
}
|
||||
|
||||
const handle = await openFile(
|
||||
absolutePath,
|
||||
constants.O_RDONLY | constants.O_NOFOLLOW,
|
||||
);
|
||||
try {
|
||||
const openedMetadata = await handle.stat();
|
||||
if (!openedMetadata.isFile()) {
|
||||
throw new TypeError(`${input.label} path is not a regular file: ${relativePath}`);
|
||||
}
|
||||
if (!sameFileIdentity(metadata, openedMetadata)) {
|
||||
throw new TypeError(`${input.label} path changed during validation: ${relativePath}`);
|
||||
}
|
||||
const text = await handle.readFile("utf8");
|
||||
return Object.freeze({ relativePath, absolutePath, text });
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
}
|
||||
|
||||
export async function resolveRiskCoverageArtifactPath(input: Readonly<{
|
||||
repositoryRoot: string;
|
||||
relativePath: string;
|
||||
inputPaths: readonly string[];
|
||||
}>): Promise<string> {
|
||||
const relativePath = normalizeRepositoryRelativePath(
|
||||
input.relativePath,
|
||||
"artifact path",
|
||||
);
|
||||
if (!relativePath.startsWith("artifacts/quality/")) {
|
||||
throw new TypeError("artifact path must be below artifacts/quality");
|
||||
}
|
||||
const normalizedInputs = input.inputPaths.map((inputPath) =>
|
||||
normalizeRepositoryRelativePath(inputPath, "input path"),
|
||||
);
|
||||
if (normalizedInputs.includes(relativePath)) {
|
||||
throw new TypeError(`artifact path must not overwrite an input: ${relativePath}`);
|
||||
}
|
||||
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot);
|
||||
const repositoryRealpath = await realpath(repositoryRoot);
|
||||
const relativeDirectory = path.posix.dirname(relativePath);
|
||||
let currentDirectory = repositoryRoot;
|
||||
let currentRelative = "";
|
||||
for (const segment of relativeDirectory.split("/")) {
|
||||
currentDirectory = path.join(currentDirectory, segment);
|
||||
currentRelative = currentRelative ? `${currentRelative}/${segment}` : segment;
|
||||
let metadata: Stats;
|
||||
try {
|
||||
metadata = await lstat(currentDirectory);
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
try {
|
||||
await mkdir(currentDirectory);
|
||||
} catch (mkdirError) {
|
||||
if (!hasErrorCode(mkdirError, "EEXIST")) throw mkdirError;
|
||||
}
|
||||
metadata = await lstat(currentDirectory);
|
||||
}
|
||||
assertDirectory(metadata, currentRelative);
|
||||
const resolvedDirectory = await realpath(currentDirectory);
|
||||
if (!isWithin(repositoryRealpath, resolvedDirectory)) {
|
||||
throw new TypeError(`artifact ancestor is outside repository: ${currentRelative}`);
|
||||
}
|
||||
}
|
||||
|
||||
const absolutePath = path.resolve(repositoryRoot, relativePath);
|
||||
let destinationMetadata: Stats | undefined;
|
||||
try {
|
||||
destinationMetadata = await lstat(absolutePath);
|
||||
if (destinationMetadata.isSymbolicLink()) {
|
||||
throw new TypeError(`artifact path is a symlink: ${relativePath}`);
|
||||
}
|
||||
if (!destinationMetadata.isFile()) {
|
||||
throw new TypeError(`artifact path is not a regular file: ${relativePath}`);
|
||||
}
|
||||
} catch (error) {
|
||||
if (!hasErrorCode(error, "ENOENT")) throw error;
|
||||
}
|
||||
if (destinationMetadata) {
|
||||
if (!hasStableIdentity(destinationMetadata)) {
|
||||
throw new TypeError("artifact stable file identity unavailable");
|
||||
}
|
||||
const destinationRealpath = await realpath(absolutePath);
|
||||
for (const inputPath of normalizedInputs) {
|
||||
const inputAbsolutePath = path.resolve(repositoryRoot, inputPath);
|
||||
const inputRealpath = await realpath(inputAbsolutePath);
|
||||
const inputMetadata = await lstat(inputAbsolutePath);
|
||||
if (!hasStableIdentity(inputMetadata)) {
|
||||
throw new TypeError(`input stable file identity unavailable: ${inputPath}`);
|
||||
}
|
||||
if (
|
||||
inputRealpath === destinationRealpath ||
|
||||
(inputMetadata.dev === destinationMetadata.dev &&
|
||||
inputMetadata.ino === destinationMetadata.ino)
|
||||
) {
|
||||
throw new TypeError(`artifact path is the same file as an input: ${inputPath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return absolutePath;
|
||||
}
|
||||
|
||||
export async function writeRiskCoverageArtifactAtomic(
|
||||
input: Readonly<{
|
||||
repositoryRoot: string;
|
||||
relativePath: string;
|
||||
inputPaths: readonly string[];
|
||||
value: unknown;
|
||||
}>,
|
||||
dependencies: WriterDependencies = {},
|
||||
): Promise<void> {
|
||||
const serialized = JSON.stringify(input.value, null, 2);
|
||||
if (serialized === undefined) {
|
||||
throw new TypeError("risk coverage artifact is not JSON serializable");
|
||||
}
|
||||
const destination = await resolveRiskCoverageArtifactPath(input);
|
||||
const temporaryPath = path.join(
|
||||
path.dirname(destination),
|
||||
`.${path.basename(destination)}.${(dependencies.createNonce ?? randomUUID)()}.tmp`,
|
||||
);
|
||||
const fileSystem = dependencies.fileSystem ?? defaultFileSystem;
|
||||
let ownsTemporaryFile = false;
|
||||
try {
|
||||
const handle = await fileSystem.openFile(
|
||||
temporaryPath,
|
||||
constants.O_WRONLY |
|
||||
constants.O_CREAT |
|
||||
constants.O_EXCL |
|
||||
constants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
ownsTemporaryFile = true;
|
||||
let primaryFailure: unknown;
|
||||
try {
|
||||
await handle.writeFile(`${serialized}\n`);
|
||||
await handle.sync();
|
||||
} catch (error) {
|
||||
primaryFailure = error;
|
||||
}
|
||||
try {
|
||||
await handle.close();
|
||||
} catch (error) {
|
||||
primaryFailure ??= error;
|
||||
}
|
||||
if (primaryFailure !== undefined) throw primaryFailure;
|
||||
|
||||
await fileSystem.rename(temporaryPath, destination);
|
||||
ownsTemporaryFile = false;
|
||||
const directoryHandle = await fileSystem.openDirectory(path.dirname(destination));
|
||||
try {
|
||||
try {
|
||||
await directoryHandle.sync();
|
||||
} catch (error) {
|
||||
// Windows and some filesystems do not support fsync on directory handles.
|
||||
if (!hasErrorCode(error, "EINVAL") && !hasErrorCode(error, "ENOTSUP")) {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
await directoryHandle.close();
|
||||
}
|
||||
} catch (error) {
|
||||
if (ownsTemporaryFile) {
|
||||
try {
|
||||
await fileSystem.rm(temporaryPath, { force: true });
|
||||
} catch {
|
||||
// Preserve the publication failure and clean only our nonce-owned path.
|
||||
}
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,901 @@
|
||||
import { constants, type Dirent, type Stats } from "node:fs";
|
||||
import {
|
||||
lstat,
|
||||
open,
|
||||
readdir,
|
||||
realpath,
|
||||
} from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import babelParser from "@babel/eslint-parser";
|
||||
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
|
||||
const coverageMetrics = [
|
||||
"lines",
|
||||
"statements",
|
||||
"functions",
|
||||
"branches",
|
||||
] as const;
|
||||
const teamIdPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
|
||||
const maximumWaiverDurationMs = 90 * 24 * 60 * 60 * 1_000;
|
||||
|
||||
export const REQUIRED_HIGH_RISK_PATHS = Object.freeze([
|
||||
"src/adapters/http/http-execution-v3.ts",
|
||||
"src/adapters/http/request-builder.ts",
|
||||
"src/adapters/http/bounded-body-reader.ts",
|
||||
"src/adapters/http/bounded-json.ts",
|
||||
"src/bootstrap/read-bounded-boot-json.ts",
|
||||
"src/adapters/service-worker/service-worker-lifecycle.ts",
|
||||
"src/adapters/query-cache/server-state-scope-runtime.ts",
|
||||
"src/bootstrap/load-release-manifest.ts",
|
||||
] as const);
|
||||
|
||||
type CoverageMetric = (typeof coverageMetrics)[number];
|
||||
type Thresholds = Readonly<Record<CoverageMetric, number>>;
|
||||
type CoverageCounter = Readonly<{
|
||||
total: number;
|
||||
covered: number;
|
||||
skipped: number;
|
||||
pct: number;
|
||||
}>;
|
||||
type CoverageMetrics = Readonly<Record<CoverageMetric, CoverageCounter>>;
|
||||
|
||||
export type RiskCoveragePolicy = Readonly<{
|
||||
schemaVersion: 2;
|
||||
repositoryBaseline: number;
|
||||
generatedPaths: readonly string[];
|
||||
summary: Thresholds;
|
||||
criticalModules: readonly Readonly<{
|
||||
path: string;
|
||||
owner: string;
|
||||
minimum: Thresholds;
|
||||
}>[];
|
||||
highRiskPaths: readonly string[];
|
||||
waivers: readonly Readonly<{
|
||||
path: string;
|
||||
owner: string;
|
||||
reason: string;
|
||||
expiresAt: string;
|
||||
}>[];
|
||||
}>;
|
||||
|
||||
export type ProductionModuleInventory = Readonly<{
|
||||
files: readonly string[];
|
||||
preExclusionTotal: number;
|
||||
generatedExclusions: readonly string[];
|
||||
counterBearingModules: readonly string[];
|
||||
counterlessModules: readonly string[];
|
||||
}>;
|
||||
|
||||
export type RiskCoverageResult = Readonly<{
|
||||
status: "PASS" | "FAIL";
|
||||
selectedTotal: number;
|
||||
repositoryTotal: number;
|
||||
counterBearingTotal: number;
|
||||
instrumentedCounterBearingTotal: number;
|
||||
counterlessTotal: number;
|
||||
counterlessModules: readonly string[];
|
||||
preExclusionTotal: number;
|
||||
generatedExclusionCount: number;
|
||||
generatedExclusions: readonly string[];
|
||||
ownershipScope: "ALL_POLICY_HIGH_RISK";
|
||||
ownedHighRiskPaths: readonly string[];
|
||||
waivedHighRiskPaths: readonly string[];
|
||||
uncoveredModules: readonly string[];
|
||||
results: readonly Readonly<{
|
||||
scope: string;
|
||||
metric: CoverageMetric;
|
||||
threshold: number;
|
||||
received: number;
|
||||
passed: boolean;
|
||||
}>[];
|
||||
failures: readonly string[];
|
||||
}>;
|
||||
|
||||
type ReadableFileHandle = Readonly<{
|
||||
stat(): Promise<Stats>;
|
||||
readFile(encoding: "utf8"): Promise<string>;
|
||||
close(): Promise<unknown>;
|
||||
}>;
|
||||
type InventoryOptions = Readonly<{
|
||||
repositoryRoot?: string;
|
||||
generatedPaths?: readonly string[];
|
||||
readDirectory?: (target: string) => Promise<Dirent[]>;
|
||||
lstatPath?: (target: string) => Promise<Stats>;
|
||||
realpathPath?: (target: string) => Promise<string>;
|
||||
openFile?: (target: string, flags: number) => Promise<ReadableFileHandle>;
|
||||
}>;
|
||||
|
||||
class FileIdentityChangedError extends Error {}
|
||||
class StableFileIdentityUnavailableError extends Error {}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function assertExactKeys(
|
||||
value: Record<string, unknown>,
|
||||
allowed: readonly string[],
|
||||
label: string,
|
||||
): void {
|
||||
const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
|
||||
if (unknown.length > 0) {
|
||||
throw new TypeError(`${label} has unknown fields: ${unknown.sort().join(", ")}`);
|
||||
}
|
||||
}
|
||||
|
||||
function exactSourcePath(value: unknown, label: string): string {
|
||||
if (
|
||||
typeof value !== "string" ||
|
||||
["*", "?", "[", "]", "{", "}"].some((character) => value.includes(character))
|
||||
) {
|
||||
throw new TypeError(`${label} must be an exact repository-relative POSIX path`);
|
||||
}
|
||||
const normalized = normalizeRepositoryRelativePath(value, label);
|
||||
if (!normalized.startsWith("src/") || !/\.tsx?$/u.test(normalized)) {
|
||||
throw new TypeError(`${label} must identify a TypeScript module below src`);
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function uniquePaths(
|
||||
value: unknown,
|
||||
label: string,
|
||||
options: Readonly<{ allowEmpty: boolean }> = { allowEmpty: true },
|
||||
): readonly string[] {
|
||||
if (!Array.isArray(value) || (!options.allowEmpty && value.length === 0)) {
|
||||
throw new TypeError(
|
||||
`${label} must be an array${options.allowEmpty ? "" : " with at least one path"}`,
|
||||
);
|
||||
}
|
||||
const paths = value.map((entry) => exactSourcePath(entry, `${label} entry`));
|
||||
if (new Set(paths).size !== paths.length) {
|
||||
throw new TypeError(`${label} contains a duplicate path`);
|
||||
}
|
||||
return Object.freeze(paths);
|
||||
}
|
||||
|
||||
function teamId(value: unknown, label: string): string {
|
||||
if (typeof value !== "string" || !teamIdPattern.test(value)) {
|
||||
throw new TypeError(`${label} must be a canonical team id`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function thresholds(value: unknown, label: string): Thresholds {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
assertExactKeys(value, coverageMetrics, label);
|
||||
if (coverageMetrics.some((metric) => !(metric in value))) {
|
||||
throw new TypeError(`${label} must define all coverage metrics`);
|
||||
}
|
||||
const parsed = {} as Record<CoverageMetric, number>;
|
||||
for (const metric of coverageMetrics) {
|
||||
const threshold = value[metric];
|
||||
if (
|
||||
typeof threshold !== "number" ||
|
||||
!Number.isFinite(threshold) ||
|
||||
threshold <= 0 ||
|
||||
threshold > 100
|
||||
) {
|
||||
throw new TypeError(
|
||||
`${label}.${metric} minimum must be a finite number greater than 0 and at most 100`,
|
||||
);
|
||||
}
|
||||
parsed[metric] = threshold;
|
||||
}
|
||||
return Object.freeze(parsed);
|
||||
}
|
||||
|
||||
function waiverReason(value: unknown, label: string): string {
|
||||
if (typeof value !== "string" || value.length < 12 || value.length > 240) {
|
||||
throw new TypeError(`${label} must contain 12 to 240 characters`);
|
||||
}
|
||||
if (value !== value.trim()) {
|
||||
throw new TypeError(`${label} must not contain surrounding whitespace`);
|
||||
}
|
||||
if (
|
||||
[...value].some((character) => {
|
||||
const codePoint = character.codePointAt(0) ?? 0;
|
||||
return codePoint <= 31 || codePoint === 127;
|
||||
})
|
||||
) {
|
||||
throw new TypeError(`${label} must not contain control characters`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
export function parseRiskCoveragePolicy(
|
||||
value: unknown,
|
||||
options: Readonly<{ now?: number }> = {},
|
||||
): RiskCoveragePolicy {
|
||||
if (!isRecord(value)) throw new TypeError("risk coverage policy must be an object");
|
||||
assertExactKeys(
|
||||
value,
|
||||
[
|
||||
"schemaVersion",
|
||||
"repositoryBaseline",
|
||||
"generatedPaths",
|
||||
"summary",
|
||||
"criticalModules",
|
||||
"highRiskPaths",
|
||||
"waivers",
|
||||
],
|
||||
"risk coverage policy",
|
||||
);
|
||||
if (value.schemaVersion !== 2) {
|
||||
throw new TypeError("risk coverage policy schemaVersion must be 2");
|
||||
}
|
||||
if (
|
||||
typeof value.repositoryBaseline !== "number" ||
|
||||
!Number.isSafeInteger(value.repositoryBaseline) ||
|
||||
value.repositoryBaseline <= 0
|
||||
) {
|
||||
throw new TypeError("repositoryBaseline must be a positive safe integer");
|
||||
}
|
||||
|
||||
const generatedPaths = uniquePaths(value.generatedPaths, "generatedPaths");
|
||||
const highRiskPaths = uniquePaths(value.highRiskPaths, "highRiskPaths", {
|
||||
allowEmpty: false,
|
||||
});
|
||||
if (!Array.isArray(value.criticalModules) || value.criticalModules.length === 0) {
|
||||
throw new TypeError("criticalModules must be a non-empty array");
|
||||
}
|
||||
const criticalModules = value.criticalModules.map((candidate, index) => {
|
||||
if (!isRecord(candidate)) {
|
||||
throw new TypeError(`criticalModules[${index}] must be an object`);
|
||||
}
|
||||
assertExactKeys(candidate, ["path", "owner", "minimum"], `criticalModules[${index}]`);
|
||||
return Object.freeze({
|
||||
path: exactSourcePath(candidate.path, `criticalModules[${index}].path`),
|
||||
owner: teamId(candidate.owner, `criticalModules[${index}].owner`),
|
||||
minimum: thresholds(candidate.minimum, `criticalModules[${index}].minimum`),
|
||||
});
|
||||
});
|
||||
if (new Set(criticalModules.map((entry) => entry.path)).size !== criticalModules.length) {
|
||||
throw new TypeError("criticalModules contains a duplicate path");
|
||||
}
|
||||
|
||||
if (!Array.isArray(value.waivers)) throw new TypeError("waivers must be an array");
|
||||
const currentTime = options.now ?? Date.now();
|
||||
if (!Number.isFinite(currentTime)) throw new TypeError("policy time must be finite");
|
||||
const waivers = value.waivers.map((candidate, index) => {
|
||||
if (!isRecord(candidate)) throw new TypeError(`waivers[${index}] must be an object`);
|
||||
assertExactKeys(candidate, ["path", "owner", "reason", "expiresAt"], `waivers[${index}]`);
|
||||
const waiverPath = exactSourcePath(candidate.path, `waivers[${index}].path`);
|
||||
const expiresAt = candidate.expiresAt;
|
||||
if (typeof expiresAt !== "string") {
|
||||
throw new TypeError(`waivers[${index}].expiresAt must be a canonical UTC ISO timestamp`);
|
||||
}
|
||||
const expiry = Date.parse(expiresAt);
|
||||
if (!Number.isFinite(expiry) || new Date(expiry).toISOString() !== expiresAt) {
|
||||
throw new TypeError(`waivers[${index}].expiresAt must be a canonical UTC ISO timestamp`);
|
||||
}
|
||||
if (expiry <= currentTime) throw new TypeError(`waivers[${index}] is expired`);
|
||||
if (expiry - currentTime > maximumWaiverDurationMs) {
|
||||
throw new TypeError(`waivers[${index}] expiry must be within 90 days`);
|
||||
}
|
||||
if (!highRiskPaths.includes(waiverPath)) {
|
||||
throw new TypeError(`waivers[${index}] is stale because ${waiverPath} is not high-risk`);
|
||||
}
|
||||
return Object.freeze({
|
||||
path: waiverPath,
|
||||
owner: teamId(candidate.owner, `waivers[${index}].owner`),
|
||||
reason: waiverReason(candidate.reason, `waivers[${index}].reason`),
|
||||
expiresAt,
|
||||
});
|
||||
});
|
||||
if (new Set(waivers.map((entry) => entry.path)).size !== waivers.length) {
|
||||
throw new TypeError("waivers contains a duplicate path");
|
||||
}
|
||||
|
||||
const criticalPaths = new Set(criticalModules.map((entry) => entry.path));
|
||||
const waiverPaths = new Set(waivers.map((entry) => entry.path));
|
||||
for (const highRiskPath of highRiskPaths) {
|
||||
if (criticalPaths.has(highRiskPath) && waiverPaths.has(highRiskPath)) {
|
||||
throw new TypeError(
|
||||
`high-risk module cannot have both a critical owner and waiver: ${highRiskPath}`,
|
||||
);
|
||||
}
|
||||
if (!criticalPaths.has(highRiskPath) && !waiverPaths.has(highRiskPath)) {
|
||||
throw new TypeError(`high-risk module has no owner or waiver: ${highRiskPath}`);
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
schemaVersion: 2,
|
||||
repositoryBaseline: value.repositoryBaseline,
|
||||
generatedPaths,
|
||||
summary: thresholds(value.summary, "summary"),
|
||||
criticalModules: Object.freeze(criticalModules),
|
||||
highRiskPaths,
|
||||
waivers: Object.freeze(waivers),
|
||||
});
|
||||
}
|
||||
|
||||
export function parseRepositoryRiskCoveragePolicy(
|
||||
value: unknown,
|
||||
options: Readonly<{ now?: number }> = {},
|
||||
): RiskCoveragePolicy {
|
||||
const policy = parseRiskCoveragePolicy(value, options);
|
||||
for (const requiredPath of REQUIRED_HIGH_RISK_PATHS) {
|
||||
if (!policy.highRiskPaths.includes(requiredPath)) {
|
||||
throw new TypeError(`required high-risk path is missing: ${requiredPath}`);
|
||||
}
|
||||
if (policy.generatedPaths.includes(requiredPath)) {
|
||||
throw new TypeError(
|
||||
`required high-risk path cannot be generated-excluded: ${requiredPath}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return policy;
|
||||
}
|
||||
|
||||
function isWithin(root: string, target: string): boolean {
|
||||
const relative = path.relative(root, target);
|
||||
return (
|
||||
relative === "" ||
|
||||
(relative !== ".." &&
|
||||
!relative.startsWith(`..${path.sep}`) &&
|
||||
!path.isAbsolute(relative))
|
||||
);
|
||||
}
|
||||
|
||||
function hasStableIdentity(metadata: Stats): boolean {
|
||||
return (
|
||||
Number.isSafeInteger(metadata.dev) &&
|
||||
Number.isSafeInteger(metadata.ino) &&
|
||||
metadata.dev > 0 &&
|
||||
metadata.ino > 0
|
||||
);
|
||||
}
|
||||
|
||||
function sameFileIdentity(before: Stats, after: Stats): boolean {
|
||||
if (!hasStableIdentity(before) || !hasStableIdentity(after)) {
|
||||
throw new StableFileIdentityUnavailableError(
|
||||
"stable file identity unavailable",
|
||||
);
|
||||
}
|
||||
return before.dev === after.dev && before.ino === after.ino;
|
||||
}
|
||||
|
||||
export function isProductionModulePath(relativePath: string): boolean {
|
||||
return (
|
||||
/\.tsx?$/u.test(relativePath) &&
|
||||
!/\.d\.ts$/u.test(relativePath) &&
|
||||
!/\.stories\.tsx?$/u.test(relativePath)
|
||||
);
|
||||
}
|
||||
|
||||
type TypeScriptAstNode = Readonly<{
|
||||
type?: unknown;
|
||||
body?: unknown;
|
||||
declaration?: unknown;
|
||||
declare?: unknown;
|
||||
const?: unknown;
|
||||
importKind?: unknown;
|
||||
}>;
|
||||
|
||||
function statementIsCoverageCounterBearing(value: unknown): boolean {
|
||||
if (!isRecord(value) || typeof value.type !== "string") {
|
||||
throw new TypeError("TypeScript parser returned an invalid statement");
|
||||
}
|
||||
const statement = value as TypeScriptAstNode;
|
||||
if (
|
||||
[
|
||||
"EmptyStatement",
|
||||
"TSDeclareFunction",
|
||||
"TSInterfaceDeclaration",
|
||||
"TSNamespaceExportDeclaration",
|
||||
"TSTypeAliasDeclaration",
|
||||
].includes(statement.type as string)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (statement.type === "ImportDeclaration") {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
statement.type === "ExportAllDeclaration" ||
|
||||
statement.type === "TSExportAssignment"
|
||||
) {
|
||||
return statement.type === "TSExportAssignment";
|
||||
}
|
||||
if (
|
||||
statement.type === "ExportNamedDeclaration" ||
|
||||
statement.type === "ExportDefaultDeclaration"
|
||||
) {
|
||||
return statement.declaration !== null && statement.declaration !== undefined
|
||||
? statementIsCoverageCounterBearing(statement.declaration)
|
||||
: false;
|
||||
}
|
||||
if (
|
||||
statement.type === "FunctionDeclaration" ||
|
||||
statement.type === "VariableDeclaration" ||
|
||||
statement.type === "ClassDeclaration" ||
|
||||
statement.type === "TSModuleDeclaration"
|
||||
) {
|
||||
return statement.declare !== true &&
|
||||
(statement.type !== "FunctionDeclaration" || statement.body !== null);
|
||||
}
|
||||
if (statement.type === "TSEnumDeclaration") {
|
||||
return statement.declare !== true && statement.const !== true;
|
||||
}
|
||||
if (statement.type === "TSImportEqualsDeclaration") {
|
||||
return statement.importKind !== "type" && statement.declare !== true;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
export function hasCoverageCounterBearingStatements(
|
||||
source: string,
|
||||
relativePath: string,
|
||||
): boolean {
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = babelParser.parse(source, {
|
||||
sourceType: "module",
|
||||
requireConfigFile: false,
|
||||
filePath: relativePath,
|
||||
babelOptions: {
|
||||
parserOpts: {
|
||||
plugins: [
|
||||
"typescript",
|
||||
...(relativePath.endsWith(".tsx") ? ["jsx"] : []),
|
||||
],
|
||||
},
|
||||
},
|
||||
});
|
||||
} catch (error) {
|
||||
throw new TypeError(`production module has invalid TypeScript syntax: ${relativePath}`, {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
if (!isRecord(parsed) || !Array.isArray(parsed.body)) {
|
||||
throw new TypeError("TypeScript parser returned an invalid program");
|
||||
}
|
||||
return parsed.body.some(statementIsCoverageCounterBearing);
|
||||
}
|
||||
|
||||
export async function buildProductionModuleInventory(
|
||||
options: InventoryOptions = {},
|
||||
): Promise<ProductionModuleInventory> {
|
||||
const repositoryRoot = path.resolve(options.repositoryRoot ?? process.cwd());
|
||||
const sourceRoot = path.join(repositoryRoot, "src");
|
||||
const readDirectory = options.readDirectory ??
|
||||
((target: string) => readdir(target, { withFileTypes: true }));
|
||||
const lstatPath = options.lstatPath ?? lstat;
|
||||
const realpathPath = options.realpathPath ?? realpath;
|
||||
const openFile = options.openFile ??
|
||||
((target: string, flags: number) => open(target, flags));
|
||||
const generatedPaths = uniquePaths(options.generatedPaths ?? [], "generatedPaths");
|
||||
const generated = new Set(generatedPaths);
|
||||
const repositoryRealpath = await realpathPath(repositoryRoot);
|
||||
const sourceMetadata = await lstatPath(sourceRoot);
|
||||
if (!sourceMetadata.isDirectory() || sourceMetadata.isSymbolicLink()) {
|
||||
throw new TypeError("production source root is not a regular directory: src");
|
||||
}
|
||||
const sourceRealpath = await realpathPath(sourceRoot);
|
||||
if (!isWithin(repositoryRealpath, sourceRealpath)) {
|
||||
throw new TypeError("production source root is outside repository");
|
||||
}
|
||||
|
||||
const allModules: string[] = [];
|
||||
const counterBearingModules: string[] = [];
|
||||
const counterlessModules: string[] = [];
|
||||
async function visit(relativeDirectory: string): Promise<void> {
|
||||
const absoluteDirectory = path.join(repositoryRoot, relativeDirectory);
|
||||
const entries = await readDirectory(absoluteDirectory);
|
||||
for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
|
||||
const relativeTarget = normalizeRepositoryRelativePath(
|
||||
`${relativeDirectory}/${entry.name}`,
|
||||
"production inventory path",
|
||||
);
|
||||
const absoluteTarget = path.join(repositoryRoot, relativeTarget);
|
||||
const metadata = await lstatPath(absoluteTarget);
|
||||
if (metadata.isSymbolicLink() || entry.isSymbolicLink()) {
|
||||
throw new TypeError(`production inventory path is a symlink: ${relativeTarget}`);
|
||||
}
|
||||
if (metadata.isDirectory()) {
|
||||
await visit(relativeTarget);
|
||||
continue;
|
||||
}
|
||||
if (!isProductionModulePath(relativeTarget)) continue;
|
||||
if (!metadata.isFile()) {
|
||||
throw new TypeError(`production inventory path is not a regular file: ${relativeTarget}`);
|
||||
}
|
||||
const resolvedTarget = await realpathPath(absoluteTarget);
|
||||
if (!isWithin(repositoryRealpath, resolvedTarget)) {
|
||||
throw new TypeError(`production inventory path is outside repository: ${relativeTarget}`);
|
||||
}
|
||||
let handle: ReadableFileHandle | undefined;
|
||||
let source: string;
|
||||
try {
|
||||
handle = await openFile(
|
||||
absoluteTarget,
|
||||
constants.O_RDONLY | constants.O_NOFOLLOW,
|
||||
);
|
||||
const openedMetadata = await handle.stat();
|
||||
if (!openedMetadata.isFile()) {
|
||||
throw new TypeError("opened target is not a regular file");
|
||||
}
|
||||
if (!sameFileIdentity(metadata, openedMetadata)) {
|
||||
throw new FileIdentityChangedError("opened file identity changed");
|
||||
}
|
||||
source = await handle.readFile("utf8");
|
||||
} catch (error) {
|
||||
if (error instanceof StableFileIdentityUnavailableError) {
|
||||
throw new Error(
|
||||
`production inventory stable file identity unavailable: ${relativeTarget}`,
|
||||
{ cause: error },
|
||||
);
|
||||
}
|
||||
if (error instanceof FileIdentityChangedError) {
|
||||
throw new Error(
|
||||
`production inventory file changed during validation: ${relativeTarget}`,
|
||||
{ cause: error },
|
||||
);
|
||||
}
|
||||
throw new Error(`production inventory file is unreadable: ${relativeTarget}`, {
|
||||
cause: error,
|
||||
});
|
||||
} finally {
|
||||
await handle?.close();
|
||||
}
|
||||
allModules.push(relativeTarget);
|
||||
if (hasCoverageCounterBearingStatements(source, relativeTarget)) {
|
||||
counterBearingModules.push(relativeTarget);
|
||||
} else {
|
||||
counterlessModules.push(relativeTarget);
|
||||
}
|
||||
}
|
||||
}
|
||||
await visit("src");
|
||||
for (const generatedPath of generatedPaths) {
|
||||
if (!allModules.includes(generatedPath)) {
|
||||
throw new TypeError(`generated path is stale or not a production module: ${generatedPath}`);
|
||||
}
|
||||
}
|
||||
const inventory = allModules.filter((file) => !generated.has(file)).sort();
|
||||
if (inventory.length === 0) throw new Error("production module inventory is empty");
|
||||
if (new Set(inventory).size !== inventory.length) {
|
||||
throw new TypeError("production module inventory contains a duplicate path");
|
||||
}
|
||||
return Object.freeze({
|
||||
files: Object.freeze(inventory),
|
||||
preExclusionTotal: allModules.length,
|
||||
generatedExclusions: Object.freeze([...generatedPaths].sort()),
|
||||
counterBearingModules: Object.freeze(
|
||||
counterBearingModules.filter((file) => !generated.has(file)).sort(),
|
||||
),
|
||||
counterlessModules: Object.freeze(
|
||||
counterlessModules.filter((file) => !generated.has(file)).sort(),
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
export function normalizeCoverageProducerPath(input: Readonly<{
|
||||
repositoryRoot: string;
|
||||
rawPath: string;
|
||||
platform?: "posix" | "win32";
|
||||
}>): string {
|
||||
const platform = input.platform ?? (process.platform === "win32" ? "win32" : "posix");
|
||||
const pathApi = platform === "win32" ? path.win32 : path.posix;
|
||||
const { rawPath } = input;
|
||||
if (rawPath.includes("\0")) throw new TypeError("coverage path contains NUL");
|
||||
if (platform === "posix" && rawPath.includes("\\")) {
|
||||
throw new TypeError("coverage path must use POSIX separators");
|
||||
}
|
||||
if (platform === "win32" && rawPath.includes("\\") && !pathApi.isAbsolute(rawPath)) {
|
||||
throw new TypeError("relative coverage path must use POSIX separators");
|
||||
}
|
||||
if (pathApi.isAbsolute(rawPath)) {
|
||||
const root = pathApi.resolve(input.repositoryRoot);
|
||||
const relative = pathApi.relative(root, pathApi.resolve(rawPath));
|
||||
if (
|
||||
!relative ||
|
||||
relative === ".." ||
|
||||
relative.startsWith(`..${pathApi.sep}`) ||
|
||||
pathApi.isAbsolute(relative)
|
||||
) {
|
||||
throw new TypeError(`coverage path is outside repository: ${rawPath}`);
|
||||
}
|
||||
return normalizeRepositoryRelativePath(
|
||||
relative.split(pathApi.sep).join("/"),
|
||||
"coverage path",
|
||||
);
|
||||
}
|
||||
return normalizeRepositoryRelativePath(rawPath, "coverage path");
|
||||
}
|
||||
|
||||
function expectedPct(total: number, covered: number): number {
|
||||
return total === 0 ? 100 : Math.floor((covered / total) * 10_000) / 100;
|
||||
}
|
||||
|
||||
function parseCoverageCounter(value: unknown, label: string): CoverageCounter {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
const fields = ["total", "covered", "skipped", "pct"] as const;
|
||||
assertExactKeys(value, fields, label);
|
||||
if (fields.some((field) => !(field in value))) {
|
||||
throw new TypeError(`${label} must define total, covered, skipped, and pct`);
|
||||
}
|
||||
for (const count of ["total", "covered", "skipped"] as const) {
|
||||
if (
|
||||
typeof value[count] !== "number" ||
|
||||
!Number.isSafeInteger(value[count]) ||
|
||||
value[count] < 0
|
||||
) {
|
||||
throw new TypeError(`${label}.${count} must be a nonnegative safe integer`);
|
||||
}
|
||||
}
|
||||
const total = value.total as number;
|
||||
const covered = value.covered as number;
|
||||
const skipped = value.skipped as number;
|
||||
if (covered + skipped > total) {
|
||||
throw new TypeError(`${label} covered plus skipped must not exceed total`);
|
||||
}
|
||||
const pct = value.pct;
|
||||
const calculatedPct = expectedPct(total, covered);
|
||||
if (typeof pct !== "number" || !Number.isFinite(pct) || pct !== calculatedPct) {
|
||||
throw new TypeError(`${label}.pct must equal ${calculatedPct}`);
|
||||
}
|
||||
return Object.freeze({ total, covered, skipped, pct });
|
||||
}
|
||||
|
||||
function parseCoverageMetrics(value: unknown, label: string): CoverageMetrics {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
const unknownMetrics = Object.keys(value).filter(
|
||||
(metric) => metric !== "branchesTrue" && !coverageMetrics.includes(metric as CoverageMetric),
|
||||
);
|
||||
if (unknownMetrics.length > 0) {
|
||||
throw new TypeError(
|
||||
`${label} has unknown coverage metric keys: ${unknownMetrics.sort().join(", ")}`,
|
||||
);
|
||||
}
|
||||
if (value.branchesTrue !== undefined) {
|
||||
parseCoverageCounter(value.branchesTrue, `${label}.branchesTrue`);
|
||||
}
|
||||
const parsed = {} as Record<CoverageMetric, CoverageCounter>;
|
||||
for (const metric of coverageMetrics) {
|
||||
parsed[metric] = parseCoverageCounter(value[metric], `${label}.${metric}`);
|
||||
}
|
||||
return Object.freeze(parsed);
|
||||
}
|
||||
|
||||
function aggregateCoverage(selected: readonly CoverageMetrics[]): CoverageMetrics {
|
||||
const aggregate = {} as Record<CoverageMetric, CoverageCounter>;
|
||||
for (const metric of coverageMetrics) {
|
||||
let total = 0;
|
||||
let covered = 0;
|
||||
let skipped = 0;
|
||||
for (const metrics of selected) {
|
||||
total += metrics[metric].total;
|
||||
covered += metrics[metric].covered;
|
||||
skipped += metrics[metric].skipped;
|
||||
if (![total, covered, skipped].every(Number.isSafeInteger)) {
|
||||
throw new TypeError(`recomputed coverage ${metric} count exceeds safe integer range`);
|
||||
}
|
||||
}
|
||||
aggregate[metric] = Object.freeze({
|
||||
total,
|
||||
covered,
|
||||
skipped,
|
||||
pct: expectedPct(total, covered),
|
||||
});
|
||||
}
|
||||
return Object.freeze(aggregate);
|
||||
}
|
||||
|
||||
function assertMatchingTotal(
|
||||
producer: CoverageMetrics,
|
||||
recomputed: CoverageMetrics,
|
||||
): void {
|
||||
for (const metric of coverageMetrics) {
|
||||
const actual = producer[metric];
|
||||
const expected = recomputed[metric];
|
||||
if (
|
||||
actual.total !== expected.total ||
|
||||
actual.covered !== expected.covered ||
|
||||
actual.skipped !== expected.skipped ||
|
||||
actual.pct !== expected.pct
|
||||
) {
|
||||
throw new TypeError(
|
||||
`coverage total.${metric} does not match recomputed inventory total`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function evaluateRiskCoverage(input: Readonly<{
|
||||
repositoryRoot?: string;
|
||||
inventory: ProductionModuleInventory;
|
||||
policy: RiskCoveragePolicy;
|
||||
summary: unknown;
|
||||
}>): RiskCoverageResult {
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot ?? process.cwd());
|
||||
const inventory = input.inventory.files.map((file) => exactSourcePath(file, "inventory path"));
|
||||
if (inventory.length === 0) throw new TypeError("production module inventory is empty");
|
||||
if (new Set(inventory).size !== inventory.length) {
|
||||
throw new TypeError("production module inventory contains a duplicate path");
|
||||
}
|
||||
const counterBearingModules = input.inventory.counterBearingModules.map((file) =>
|
||||
exactSourcePath(file, "counter-bearing inventory path"),
|
||||
);
|
||||
const counterlessModules = input.inventory.counterlessModules.map((file) =>
|
||||
exactSourcePath(file, "counterless inventory path"),
|
||||
);
|
||||
const counterBearingSet = new Set(counterBearingModules);
|
||||
const counterlessSet = new Set(counterlessModules);
|
||||
const partition = [...counterBearingModules, ...counterlessModules].sort();
|
||||
if (
|
||||
counterBearingSet.size !== counterBearingModules.length ||
|
||||
counterlessSet.size !== counterlessModules.length ||
|
||||
counterBearingModules.some((file) => counterlessSet.has(file)) ||
|
||||
partition.join("\n") !== [...inventory].sort().join("\n")
|
||||
) {
|
||||
throw new TypeError("production inventory counter-bearing provenance is inconsistent");
|
||||
}
|
||||
const generatedExclusions = input.inventory.generatedExclusions.map((file) =>
|
||||
exactSourcePath(file, "generated exclusion"),
|
||||
);
|
||||
if (
|
||||
new Set(generatedExclusions).size !== generatedExclusions.length ||
|
||||
input.inventory.preExclusionTotal !== inventory.length + generatedExclusions.length ||
|
||||
!Number.isSafeInteger(input.inventory.preExclusionTotal)
|
||||
) {
|
||||
throw new TypeError("production inventory provenance is inconsistent");
|
||||
}
|
||||
const policyGenerated = [...input.policy.generatedPaths].sort();
|
||||
if (generatedExclusions.join("\n") !== policyGenerated.join("\n")) {
|
||||
throw new TypeError("production inventory generated exclusions do not match policy");
|
||||
}
|
||||
if (!isRecord(input.summary) || !("total" in input.summary)) {
|
||||
throw new TypeError("coverage summary must contain total metrics");
|
||||
}
|
||||
const totalMetrics = parseCoverageMetrics(input.summary.total, "coverage total");
|
||||
const selected = new Map<string, CoverageMetrics>();
|
||||
for (const [rawPath, rawMetrics] of Object.entries(input.summary)) {
|
||||
if (rawPath === "total") continue;
|
||||
const normalized = normalizeCoverageProducerPath({ repositoryRoot, rawPath });
|
||||
if (selected.has(normalized)) throw new TypeError(`duplicate coverage path: ${normalized}`);
|
||||
selected.set(normalized, parseCoverageMetrics(rawMetrics, `coverage ${normalized}`));
|
||||
}
|
||||
|
||||
const inventorySet = new Set(inventory);
|
||||
const generatedSet = new Set(generatedExclusions);
|
||||
for (const selectedPath of selected.keys()) {
|
||||
if (!inventorySet.has(selectedPath) && !generatedSet.has(selectedPath)) {
|
||||
throw new TypeError(`unexpected coverage path outside inventory: ${selectedPath}`);
|
||||
}
|
||||
}
|
||||
const inventoryMetrics = inventory.flatMap((file) => {
|
||||
const metrics = selected.get(file);
|
||||
return metrics ? [metrics] : [];
|
||||
});
|
||||
const zeroCoverageModules = inventory.filter((file) => {
|
||||
const metrics = selected.get(file);
|
||||
return (
|
||||
metrics !== undefined &&
|
||||
coverageMetrics.every((metric) => metrics[metric].total === 0)
|
||||
);
|
||||
});
|
||||
const zeroCoverageSet = new Set(zeroCoverageModules);
|
||||
const zeroCounterBearingModules = zeroCoverageModules.filter((file) =>
|
||||
counterBearingSet.has(file),
|
||||
);
|
||||
const counterlessWithCounters = counterlessModules.filter((file) => {
|
||||
const metrics = selected.get(file);
|
||||
return metrics !== undefined && !zeroCoverageSet.has(file);
|
||||
});
|
||||
const instrumentedCounterBearingTotal = counterBearingModules.filter((file) => {
|
||||
const metrics = selected.get(file);
|
||||
return metrics !== undefined && !zeroCoverageSet.has(file);
|
||||
}).length;
|
||||
assertMatchingTotal(totalMetrics, aggregateCoverage([...selected.values()]));
|
||||
const recomputedInventoryMetrics = aggregateCoverage(inventoryMetrics);
|
||||
|
||||
const failures: string[] = [];
|
||||
const results: Array<{
|
||||
scope: string;
|
||||
metric: CoverageMetric;
|
||||
threshold: number;
|
||||
received: number;
|
||||
passed: boolean;
|
||||
}> = [];
|
||||
function evaluate(scope: string, actual: CoverageMetrics, minimum: Thresholds): void {
|
||||
for (const metric of coverageMetrics) {
|
||||
const threshold = minimum[metric];
|
||||
const received = actual[metric].pct;
|
||||
const hasCoverageTotal = actual[metric].total > 0;
|
||||
const passed = hasCoverageTotal && received >= threshold;
|
||||
results.push({ scope, metric, threshold, received, passed });
|
||||
if (!hasCoverageTotal) {
|
||||
failures.push(`${scope}.${metric} coverage total must be greater than 0`);
|
||||
} else if (!passed) {
|
||||
failures.push(`${scope}.${metric} expected >= ${threshold}, received ${received}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
evaluate("total", recomputedInventoryMetrics, input.policy.summary);
|
||||
if (inventory.length < input.policy.repositoryBaseline) {
|
||||
failures.push(
|
||||
`repository module baseline expected >= ${input.policy.repositoryBaseline}, received ${inventory.length}`,
|
||||
);
|
||||
}
|
||||
const uncoveredModules = inventory
|
||||
.filter(
|
||||
(file) =>
|
||||
!selected.has(file) ||
|
||||
(counterBearingSet.has(file) && zeroCoverageSet.has(file)),
|
||||
)
|
||||
.sort();
|
||||
failures.push(
|
||||
...inventory
|
||||
.filter((file) => !selected.has(file))
|
||||
.map((file) => `production module missing from coverage: ${file}`),
|
||||
...zeroCounterBearingModules.map(
|
||||
(file) => `counter-bearing module has zero coverage totals: ${file}`,
|
||||
),
|
||||
...counterlessWithCounters.map(
|
||||
(file) => `counterless module has coverage counters: ${file}`,
|
||||
),
|
||||
);
|
||||
for (const modulePolicy of input.policy.criticalModules) {
|
||||
if (!inventorySet.has(modulePolicy.path)) {
|
||||
failures.push(`critical module is outside production inventory: ${modulePolicy.path}`);
|
||||
continue;
|
||||
}
|
||||
if (counterlessSet.has(modulePolicy.path)) {
|
||||
failures.push(
|
||||
`critical policy-sensitive module cannot be counterless: ${modulePolicy.path}`,
|
||||
);
|
||||
}
|
||||
const actual = selected.get(modulePolicy.path);
|
||||
if (!actual) {
|
||||
failures.push(`critical module missing from coverage: ${modulePolicy.path}`);
|
||||
continue;
|
||||
}
|
||||
evaluate(modulePolicy.path, actual, modulePolicy.minimum);
|
||||
}
|
||||
|
||||
const criticalPaths = new Set(input.policy.criticalModules.map((entry) => entry.path));
|
||||
const waiverPaths = new Set(input.policy.waivers.map((entry) => entry.path));
|
||||
for (const highRiskPath of input.policy.highRiskPaths) {
|
||||
if (!inventorySet.has(highRiskPath)) {
|
||||
failures.push(`high-risk module is outside production inventory: ${highRiskPath}`);
|
||||
}
|
||||
if (counterlessSet.has(highRiskPath)) {
|
||||
failures.push(
|
||||
`high-risk policy-sensitive module cannot be counterless: ${highRiskPath}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
for (const waiver of input.policy.waivers) {
|
||||
if (!inventorySet.has(waiver.path)) failures.push(`coverage waiver is stale: ${waiver.path}`);
|
||||
}
|
||||
const ownedHighRiskPaths = input.policy.highRiskPaths
|
||||
.filter((modulePath) => criticalPaths.has(modulePath))
|
||||
.sort();
|
||||
const waivedHighRiskPaths = input.policy.highRiskPaths
|
||||
.filter((modulePath) => waiverPaths.has(modulePath))
|
||||
.sort();
|
||||
|
||||
return Object.freeze({
|
||||
status: failures.length === 0 ? "PASS" : "FAIL",
|
||||
selectedTotal: inventory.length - uncoveredModules.length,
|
||||
repositoryTotal: inventory.length,
|
||||
counterBearingTotal: counterBearingModules.length,
|
||||
instrumentedCounterBearingTotal,
|
||||
counterlessTotal: counterlessModules.length,
|
||||
counterlessModules: Object.freeze([...counterlessModules].sort()),
|
||||
preExclusionTotal: input.inventory.preExclusionTotal,
|
||||
generatedExclusionCount: generatedExclusions.length,
|
||||
generatedExclusions: Object.freeze([...generatedExclusions].sort()),
|
||||
ownershipScope: "ALL_POLICY_HIGH_RISK",
|
||||
ownedHighRiskPaths: Object.freeze(ownedHighRiskPaths),
|
||||
waivedHighRiskPaths: Object.freeze(waivedHighRiskPaths),
|
||||
uncoveredModules: Object.freeze(uncoveredModules),
|
||||
results: Object.freeze(results),
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
buildRepositoryFileInventory,
|
||||
parseRepositoryFileInventoryPolicy,
|
||||
} from "./repository-file-inventory.ts";
|
||||
import {
|
||||
findSecretMatches,
|
||||
secretScanRules,
|
||||
type SecretAllowlistEntry,
|
||||
type SecretFinding,
|
||||
} from "./secret-scan.ts";
|
||||
import {
|
||||
parseSecretScanIncludedPaths,
|
||||
selectIncludedInventoryFiles,
|
||||
} from "./secret-scan-policy.ts";
|
||||
import { supplyChainDigest } from "./supply-chain.ts";
|
||||
|
||||
const nonEmptyString = z.string().min(1);
|
||||
const sarifRuleSchema = z
|
||||
.object({
|
||||
id: nonEmptyString,
|
||||
shortDescription: z.object({ text: nonEmptyString }).strict(),
|
||||
})
|
||||
.strict();
|
||||
const sarifResultSchema = z
|
||||
.object({
|
||||
ruleId: nonEmptyString,
|
||||
message: z.object({ text: nonEmptyString }).strict(),
|
||||
partialFingerprints: z
|
||||
.object({ primaryLocationLineHash: nonEmptyString })
|
||||
.strict()
|
||||
.optional(),
|
||||
locations: z
|
||||
.array(
|
||||
z
|
||||
.object({
|
||||
physicalLocation: z
|
||||
.object({
|
||||
artifactLocation: z.object({ uri: nonEmptyString }).strict(),
|
||||
region: z.object({ startLine: z.int().positive() }).strict(),
|
||||
})
|
||||
.strict(),
|
||||
})
|
||||
.strict(),
|
||||
)
|
||||
.optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export const secretScanSarifSchema = z
|
||||
.object({
|
||||
version: z.literal("2.1.0"),
|
||||
$schema: z.literal("https://json.schemastore.org/sarif-2.1.0.json"),
|
||||
runs: z
|
||||
.array(
|
||||
z
|
||||
.object({
|
||||
tool: z
|
||||
.object({
|
||||
driver: z
|
||||
.object({
|
||||
name: z.literal("ca-frontend-secret-scan"),
|
||||
rules: z.array(sarifRuleSchema),
|
||||
})
|
||||
.strict(),
|
||||
})
|
||||
.strict(),
|
||||
results: z.array(sarifResultSchema),
|
||||
})
|
||||
.strict(),
|
||||
)
|
||||
.length(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
type AllowlistEntry = SecretAllowlistEntry &
|
||||
Readonly<{ owner: string; reason: string }>;
|
||||
export type SecretScanPolicy = Readonly<{
|
||||
excludedPaths: readonly string[];
|
||||
trackedRoots: readonly string[];
|
||||
generatedRoots: readonly string[];
|
||||
optionalRoots: readonly string[];
|
||||
includedPaths: readonly string[] | null;
|
||||
allowlist: readonly AllowlistEntry[];
|
||||
}>;
|
||||
|
||||
export function parseSecretScanPolicy(value: unknown): SecretScanPolicy {
|
||||
const document = isRecord(value) ? value : {};
|
||||
const inventoryPolicy = parseRepositoryFileInventoryPolicy(value);
|
||||
const allowlist = Array.isArray(document.allowlist)
|
||||
? document.allowlist.map((rawEntry) => {
|
||||
const entry = isRecord(rawEntry) ? rawEntry : {};
|
||||
return Object.freeze({
|
||||
path: typeof entry.path === "string" ? entry.path : "",
|
||||
ruleId: typeof entry.ruleId === "string" ? entry.ruleId : "",
|
||||
owner: typeof entry.owner === "string" ? entry.owner : "",
|
||||
reason: typeof entry.reason === "string" ? entry.reason : "",
|
||||
expiresAt:
|
||||
typeof entry.expiresAt === "string" ? entry.expiresAt : "",
|
||||
});
|
||||
})
|
||||
: [];
|
||||
return Object.freeze({
|
||||
excludedPaths: Object.freeze(strings(document.excludedPaths)),
|
||||
trackedRoots: inventoryPolicy.trackedRoots,
|
||||
generatedRoots: inventoryPolicy.generatedRoots,
|
||||
optionalRoots: inventoryPolicy.optionalRoots,
|
||||
includedPaths: parseSecretScanIncludedPaths(document.includedPaths),
|
||||
allowlist: Object.freeze(allowlist),
|
||||
});
|
||||
}
|
||||
|
||||
export async function evaluateRepositorySecretScan(input: Readonly<{
|
||||
repositoryRoot?: string;
|
||||
policyPath?: string;
|
||||
now?: number;
|
||||
}>) {
|
||||
const repositoryRoot = path.resolve(input.repositoryRoot ?? process.cwd());
|
||||
const policy = parseSecretScanPolicy(
|
||||
JSON.parse(
|
||||
await readFile(
|
||||
path.resolve(
|
||||
repositoryRoot,
|
||||
input.policyPath ?? "config/security/secret-scan-policy.json",
|
||||
),
|
||||
"utf8",
|
||||
),
|
||||
) as unknown,
|
||||
);
|
||||
const inventory = await buildRepositoryFileInventory({
|
||||
repositoryRoot,
|
||||
trackedRoots: policy.trackedRoots,
|
||||
generatedRoots: policy.generatedRoots,
|
||||
optionalRoots: policy.optionalRoots,
|
||||
});
|
||||
return evaluateSecretScan({
|
||||
policy,
|
||||
inventoryFiles: inventory.files,
|
||||
readText: (file) => readFile(path.join(repositoryRoot, file), "utf8"),
|
||||
now: input.now,
|
||||
});
|
||||
}
|
||||
|
||||
export async function evaluateSecretScan(input: Readonly<{
|
||||
policy: SecretScanPolicy;
|
||||
inventoryFiles: readonly string[];
|
||||
readText: (file: string) => Promise<string>;
|
||||
now?: number;
|
||||
}>) {
|
||||
const now = input.now ?? Date.now();
|
||||
const findings: SecretFinding[] = [];
|
||||
const policyFailures: string[] = [];
|
||||
for (const entry of input.policy.allowlist) {
|
||||
const expiry = Date.parse(entry.expiresAt);
|
||||
if (
|
||||
!entry.path.startsWith("tests/") ||
|
||||
!entry.owner.trim() ||
|
||||
!entry.reason.trim() ||
|
||||
!Number.isFinite(expiry) ||
|
||||
expiry <= now
|
||||
) {
|
||||
policyFailures.push(
|
||||
`invalid or expired secret allowlist entry: ${entry.path}:${entry.ruleId}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
const scanFiles = selectIncludedInventoryFiles(
|
||||
input.inventoryFiles,
|
||||
input.policy.includedPaths,
|
||||
);
|
||||
const excluded = new Set(
|
||||
input.policy.excludedPaths.map((entry) => entry.replaceAll("\\", "/")),
|
||||
);
|
||||
const scanInputs: Readonly<{ path: string; bytes: number; sha256: string }>[] = [];
|
||||
for (const scanFile of [...new Set(scanFiles)].sort()) {
|
||||
const normalized = scanFile.replaceAll("\\", "/");
|
||||
if (
|
||||
[...excluded].some(
|
||||
(entry) =>
|
||||
normalized === entry || normalized.startsWith(`${entry}/`),
|
||||
) ||
|
||||
/\.(?:png|jpe?g|gif|webp|woff2?|zip|gz|sarif)$/iu.test(normalized)
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
const content = await input.readText(scanFile);
|
||||
const bytes = Buffer.from(content, "utf8");
|
||||
scanInputs.push(Object.freeze({
|
||||
path: normalized,
|
||||
bytes: bytes.byteLength,
|
||||
sha256: createHash("sha256").update(bytes).digest("hex"),
|
||||
}));
|
||||
findings.push(
|
||||
...findSecretMatches(normalized, content, {
|
||||
allowlist: input.policy.allowlist,
|
||||
now,
|
||||
}),
|
||||
);
|
||||
}
|
||||
const sarif = secretScanSarifSchema.parse({
|
||||
version: "2.1.0",
|
||||
$schema: "https://json.schemastore.org/sarif-2.1.0.json",
|
||||
runs: [
|
||||
{
|
||||
tool: {
|
||||
driver: {
|
||||
name: "ca-frontend-secret-scan",
|
||||
rules: secretScanRules().map((pattern) => ({
|
||||
id: pattern.id,
|
||||
shortDescription: { text: "Potential credential material" },
|
||||
})),
|
||||
},
|
||||
},
|
||||
results: [
|
||||
...findings.map((finding) => ({
|
||||
ruleId: finding.ruleId,
|
||||
message: { text: "Potential secret material must be removed." },
|
||||
partialFingerprints: {
|
||||
primaryLocationLineHash: finding.fingerprint,
|
||||
},
|
||||
locations: [
|
||||
{
|
||||
physicalLocation: {
|
||||
artifactLocation: { uri: finding.file },
|
||||
region: { startLine: finding.line },
|
||||
},
|
||||
},
|
||||
],
|
||||
})),
|
||||
...policyFailures.map((failure) => ({
|
||||
ruleId: "invalid-allowlist",
|
||||
message: { text: failure },
|
||||
})),
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
return Object.freeze({
|
||||
findings: Object.freeze(findings),
|
||||
policyFailures: Object.freeze(policyFailures),
|
||||
scanFiles: Object.freeze([...scanFiles]),
|
||||
scanInputs: Object.freeze(scanInputs),
|
||||
scanInputSha256: supplyChainDigest(scanInputs),
|
||||
sarif,
|
||||
});
|
||||
}
|
||||
|
||||
export function verifyStoredSecretScan(
|
||||
evaluation: Awaited<ReturnType<typeof evaluateSecretScan>>,
|
||||
stored: unknown,
|
||||
): string[] {
|
||||
const failures: string[] = [];
|
||||
const blockingCount =
|
||||
evaluation.findings.length + evaluation.policyFailures.length;
|
||||
if (blockingCount > 0) {
|
||||
failures.push(
|
||||
`recomputed secret scan contains ${blockingCount} blocking result(s)`,
|
||||
);
|
||||
}
|
||||
const parsed = secretScanSarifSchema.safeParse(stored);
|
||||
if (
|
||||
!parsed.success ||
|
||||
supplyChainDigest(parsed.data) !== supplyChainDigest(evaluation.sarif)
|
||||
) {
|
||||
failures.push("stored secret scan SARIF does not match recomputed results");
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
function strings(value: unknown): string[] {
|
||||
return Array.isArray(value)
|
||||
? value.filter((entry): entry is string => typeof entry === "string")
|
||||
: [];
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
|
||||
export function parseSecretScanIncludedPaths(
|
||||
value: unknown,
|
||||
): readonly string[] | null {
|
||||
if (value === undefined) return null;
|
||||
if (
|
||||
!Array.isArray(value) ||
|
||||
value.length === 0 ||
|
||||
value.some(
|
||||
(entry) =>
|
||||
typeof entry !== "string" ||
|
||||
entry.length === 0 ||
|
||||
entry.trim() !== entry,
|
||||
)
|
||||
) {
|
||||
throw new TypeError(
|
||||
"includedPaths must be a non-empty array of repository-relative POSIX paths",
|
||||
);
|
||||
}
|
||||
const normalized = value.map((entry) =>
|
||||
normalizeRepositoryRelativePath(entry as string, "included path"),
|
||||
);
|
||||
if (new Set(normalized).size !== normalized.length) {
|
||||
throw new TypeError("includedPaths must not contain duplicate paths");
|
||||
}
|
||||
return Object.freeze(normalized);
|
||||
}
|
||||
|
||||
export function selectIncludedInventoryFiles(
|
||||
inventoryFiles: readonly string[],
|
||||
includedPaths: readonly string[] | null,
|
||||
): readonly string[] {
|
||||
if (includedPaths === null) return Object.freeze([...inventoryFiles]);
|
||||
const validatedIncludedPaths = parseSecretScanIncludedPaths(includedPaths);
|
||||
if (validatedIncludedPaths === null) {
|
||||
throw new TypeError("includedPaths unexpectedly omitted");
|
||||
}
|
||||
for (const includedPath of validatedIncludedPaths) {
|
||||
if (
|
||||
!inventoryFiles.some(
|
||||
(file) =>
|
||||
file === includedPath || file.startsWith(`${includedPath}/`),
|
||||
)
|
||||
) {
|
||||
throw new Error(
|
||||
`secret scan included path matches no inventory file: ${includedPath}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze(
|
||||
inventoryFiles.filter((file) =>
|
||||
validatedIncludedPaths.some(
|
||||
(includedPath) =>
|
||||
file === includedPath || file.startsWith(`${includedPath}/`),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
export type SecretFinding = Readonly<{
|
||||
ruleId: string;
|
||||
file: string;
|
||||
line: number;
|
||||
fingerprint: string;
|
||||
}>;
|
||||
|
||||
export type SecretAllowlistEntry = Readonly<{
|
||||
path: string;
|
||||
ruleId: string;
|
||||
expiresAt: string;
|
||||
}>;
|
||||
|
||||
const secretPatterns: readonly Readonly<{
|
||||
id: string;
|
||||
expression: RegExp;
|
||||
}>[] = [
|
||||
{
|
||||
id: "private-key",
|
||||
expression: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/g,
|
||||
},
|
||||
{ id: "aws-access-key", expression: /\bAKIA[0-9A-Z]{16}\b/g },
|
||||
{ id: "github-token", expression: /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/g },
|
||||
{
|
||||
id: "assigned-secret",
|
||||
expression:
|
||||
/(?<![\w])(["']?)(?:client_secret|password|private_key)\1(?![\w])\s*[:=]\s*["'][^"'${}]{12,}["']/gi,
|
||||
},
|
||||
];
|
||||
|
||||
export function secretScanRules(): readonly Readonly<{
|
||||
id: string;
|
||||
expression: RegExp;
|
||||
}>[] {
|
||||
return secretPatterns;
|
||||
}
|
||||
|
||||
export function findSecretMatches(
|
||||
file: string,
|
||||
content: string,
|
||||
options: Readonly<{
|
||||
allowlist?: readonly SecretAllowlistEntry[];
|
||||
now?: number;
|
||||
}> = {},
|
||||
): SecretFinding[] {
|
||||
const allowlist = options.allowlist ?? [];
|
||||
const now = options.now ?? Date.now();
|
||||
const findings: SecretFinding[] = [];
|
||||
for (const pattern of secretPatterns) {
|
||||
pattern.expression.lastIndex = 0;
|
||||
for (const match of content.matchAll(pattern.expression)) {
|
||||
const isAllowed = allowlist.some(
|
||||
(entry) =>
|
||||
entry.path === file &&
|
||||
entry.ruleId === pattern.id &&
|
||||
Date.parse(entry.expiresAt) > now,
|
||||
);
|
||||
if (isAllowed) continue;
|
||||
const matchIndex = match.index ?? 0;
|
||||
findings.push({
|
||||
ruleId: pattern.id,
|
||||
file,
|
||||
line: content.slice(0, matchIndex).split(/\r?\n/u).length,
|
||||
fingerprint: createHash("sha256")
|
||||
.update(`${pattern.id}:${file}:${String(matchIndex)}`)
|
||||
.digest("hex"),
|
||||
});
|
||||
}
|
||||
}
|
||||
return findings;
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdtemp, readFile, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
type ScanResult = Readonly<{
|
||||
error?: Error;
|
||||
status: number | null;
|
||||
signal: NodeJS.Signals | null;
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
}>;
|
||||
|
||||
type SecurityFixtureCheckDependencies = Readonly<{
|
||||
createTempDirectory?: () => Promise<string>;
|
||||
runScan?: (artifactPath: string, policyPath: string) => ScanResult;
|
||||
readArtifact?: (artifactPath: string) => Promise<string>;
|
||||
cleanup?: (directory: string) => Promise<void>;
|
||||
}>;
|
||||
|
||||
type Document = Record<string, unknown>;
|
||||
|
||||
function record(value: unknown, label: string): Document {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new TypeError(`${label} must be an object`);
|
||||
}
|
||||
return value as Document;
|
||||
}
|
||||
|
||||
function defaultScan(artifactPath: string, policyPath: string): ScanResult {
|
||||
const scan = spawnSync(
|
||||
"node",
|
||||
[
|
||||
"scripts/security-scan.ts",
|
||||
"--policy",
|
||||
policyPath,
|
||||
"--artifact",
|
||||
artifactPath,
|
||||
],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
return {
|
||||
...(scan.error ? { error: scan.error } : {}),
|
||||
status: scan.status,
|
||||
signal: scan.signal,
|
||||
stdout: scan.stdout ?? "",
|
||||
stderr: scan.stderr ?? "",
|
||||
};
|
||||
}
|
||||
|
||||
function assertExactFindings(rawArtifact: string): void {
|
||||
const sarif = record(JSON.parse(rawArtifact), "security fixture SARIF");
|
||||
const runs = Array.isArray(sarif.runs) ? sarif.runs : [];
|
||||
const run = record(runs[0], "security fixture SARIF run");
|
||||
const results = Array.isArray(run.results) ? run.results : [];
|
||||
const actual = results
|
||||
.map((rawResult) => {
|
||||
const result = record(rawResult, "security fixture result");
|
||||
const locations = Array.isArray(result.locations) ? result.locations : [];
|
||||
const location = record(locations[0], "security fixture location");
|
||||
const physical = record(
|
||||
location.physicalLocation,
|
||||
"security fixture physical location",
|
||||
);
|
||||
const artifactLocation = record(
|
||||
physical.artifactLocation,
|
||||
"security fixture artifact location",
|
||||
);
|
||||
return `${String(artifactLocation.uri)}:${String(result.ruleId)}`;
|
||||
})
|
||||
.sort();
|
||||
const root = "tests/fixtures/security/secret-detection/forbidden";
|
||||
const expected = [
|
||||
`${root}/config.json:assigned-secret`,
|
||||
`${root}/dist.ts:assigned-secret`,
|
||||
`${root}/source.ts:aws-access-key`,
|
||||
].sort();
|
||||
if (JSON.stringify(actual) !== JSON.stringify(expected)) {
|
||||
throw new Error(
|
||||
`security fixture findings mismatch: expected ${expected.join(", ")}; received ${actual.join(", ")}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export async function checkSecurityFixtures(
|
||||
dependencies: SecurityFixtureCheckDependencies = {},
|
||||
): Promise<void> {
|
||||
const createTempDirectory =
|
||||
dependencies.createTempDirectory ??
|
||||
(() => mkdtemp(path.join(tmpdir(), "ca-security-fixture-")));
|
||||
const runScan = dependencies.runScan ?? defaultScan;
|
||||
const readArtifact = dependencies.readArtifact ?? ((target) => readFile(target, "utf8"));
|
||||
const cleanup =
|
||||
dependencies.cleanup ??
|
||||
((directory) => rm(directory, { recursive: true, force: true }));
|
||||
const directory = await createTempDirectory();
|
||||
const artifactPath = path.join(directory, "scan-fixture.sarif");
|
||||
try {
|
||||
const scan = runScan(
|
||||
artifactPath,
|
||||
"tests/fixtures/security/secret-detection/forbidden-policy.json",
|
||||
);
|
||||
const expectedDiagnostic = "Security scan found 3 blocking result(s).";
|
||||
if (
|
||||
scan.error ||
|
||||
scan.status !== 1 ||
|
||||
scan.signal !== null ||
|
||||
scan.stderr !== `${expectedDiagnostic}\n`
|
||||
) {
|
||||
throw new Error(
|
||||
`forbidden security fixture did not fail exactly: ${scan.error?.message ?? scan.stderr}`,
|
||||
);
|
||||
}
|
||||
assertExactFindings(await readArtifact(artifactPath));
|
||||
} finally {
|
||||
await cleanup(directory);
|
||||
}
|
||||
}
|
||||
|
||||
export async function checkNonmatchingSecurityIncludeFixture(
|
||||
dependencies: SecurityFixtureCheckDependencies = {},
|
||||
): Promise<void> {
|
||||
const createTempDirectory =
|
||||
dependencies.createTempDirectory ??
|
||||
(() => mkdtemp(path.join(tmpdir(), "ca-security-include-fixture-")));
|
||||
const runScan = dependencies.runScan ?? defaultScan;
|
||||
const readArtifact =
|
||||
dependencies.readArtifact ?? ((target) => readFile(target, "utf8"));
|
||||
const cleanup =
|
||||
dependencies.cleanup ??
|
||||
((directory) => rm(directory, { recursive: true, force: true }));
|
||||
const directory = await createTempDirectory();
|
||||
const artifactPath = path.join(directory, "scan-fixture.sarif");
|
||||
try {
|
||||
const includedPath =
|
||||
"tests/fixtures/security/secret-detection/misspelled";
|
||||
const scan = runScan(
|
||||
artifactPath,
|
||||
"tests/fixtures/security/secret-detection/nonmatching-policy.json",
|
||||
);
|
||||
if (
|
||||
scan.error ||
|
||||
scan.status !== 1 ||
|
||||
scan.signal !== null ||
|
||||
!scan.stderr.includes(
|
||||
`secret scan included path matches no inventory file: ${includedPath}`,
|
||||
)
|
||||
) {
|
||||
throw new Error(
|
||||
`nonmatching security include fixture did not fail closed: ${scan.error?.message ?? scan.stderr}`,
|
||||
);
|
||||
}
|
||||
try {
|
||||
await readArtifact(artifactPath);
|
||||
} catch (error) {
|
||||
if (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
"code" in error &&
|
||||
error.code === "ENOENT"
|
||||
) {
|
||||
return;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
throw new Error("nonmatching security include fixture wrote an artifact");
|
||||
} finally {
|
||||
await cleanup(directory);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import {
|
||||
canonicalStaticManifestBytes,
|
||||
decodeStaticAssetManifest,
|
||||
} from "../../src/contracts/service-worker-static-manifest.ts";
|
||||
|
||||
import type {
|
||||
InstalledServiceWorkerSelection,
|
||||
ServiceWorkerHandlerId,
|
||||
StaticAssetManifestV1,
|
||||
} from "../../src/contracts/service-worker.ts";
|
||||
|
||||
const DIGEST = /^sha256:[0-9a-f]{64}$/u;
|
||||
|
||||
export type ServiceWorkerBuildInput = Readonly<{
|
||||
assets: StaticAssetManifestV1;
|
||||
handlers: readonly ServiceWorkerHandlerId[];
|
||||
contractSetDigest: string;
|
||||
releaseManifestUrl: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* ACTIVE worker compilation is a release-integrity boundary. Missing generated
|
||||
* modules, stale identities and placeholder digests are fatal build defects;
|
||||
* they must never be converted into a worker that merely degrades at runtime.
|
||||
*/
|
||||
export function resolveServiceWorkerBuildInput(input: Readonly<{
|
||||
selection: InstalledServiceWorkerSelection | null;
|
||||
assets: unknown;
|
||||
contractSet: unknown;
|
||||
runtimeConfig: unknown;
|
||||
buildId: string;
|
||||
releaseId: string;
|
||||
}>): ServiceWorkerBuildInput {
|
||||
if (input.selection?.mode !== "ACTIVE") {
|
||||
throw new TypeError(
|
||||
"Service Worker build requires an ACTIVE static selection.",
|
||||
);
|
||||
}
|
||||
if (!Array.isArray(input.selection.handlers)) {
|
||||
throw new TypeError("Service Worker handlers must be an array.");
|
||||
}
|
||||
const handlers = new Set<ServiceWorkerHandlerId>();
|
||||
for (const handler of input.selection.handlers) {
|
||||
if (
|
||||
handler !== "PWA_STATIC_ASSETS" &&
|
||||
handler !== "OFFLINE_SYNC_WAKEUP" &&
|
||||
handler !== "WEB_PUSH"
|
||||
) {
|
||||
throw new TypeError(`Unknown Service Worker handler: ${String(handler)}.`);
|
||||
}
|
||||
if (handlers.has(handler)) {
|
||||
throw new TypeError(`Duplicate Service Worker handler: ${handler}.`);
|
||||
}
|
||||
handlers.add(handler);
|
||||
}
|
||||
if (handlers.has("WEB_PUSH")) {
|
||||
throw new TypeError(
|
||||
"WEB_PUSH requires an installed product-owned worker contribution.",
|
||||
);
|
||||
}
|
||||
const assets = parseAssets(input.assets);
|
||||
if (assets.buildId !== input.buildId || assets.releaseId !== input.releaseId) {
|
||||
throw new TypeError("Generated Service Worker asset identity is stale.");
|
||||
}
|
||||
const contractSet = record(input.contractSet);
|
||||
const contractSetDigest = contractSet?.setDigest;
|
||||
if (typeof contractSetDigest !== "string" || !DIGEST.test(contractSetDigest)) {
|
||||
throw new TypeError("Generated contract set digest is invalid.");
|
||||
}
|
||||
const runtimeConfig = record(input.runtimeConfig);
|
||||
const releaseManifestUrl = runtimeConfig?.RELEASE_MANIFEST_URL;
|
||||
if (
|
||||
typeof releaseManifestUrl !== "string" ||
|
||||
releaseManifestUrl.length === 0 ||
|
||||
releaseManifestUrl.length > 2_048
|
||||
) {
|
||||
throw new TypeError("Runtime release manifest URL is invalid.");
|
||||
}
|
||||
return Object.freeze({
|
||||
assets,
|
||||
handlers: Object.freeze([...handlers]),
|
||||
contractSetDigest,
|
||||
releaseManifestUrl,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* SW-05. The build gate no longer type-casts the manifest. It decodes every row
|
||||
* through the shared runtime-neutral codec and recomputes the set digest from
|
||||
* the same canonical bytes the generator hashed, so a tampered row, a reordered
|
||||
* set or a stale digest fails admission instead of shipping.
|
||||
*/
|
||||
function parseAssets(value: unknown): StaticAssetManifestV1 {
|
||||
const decoded = decodeStaticAssetManifest(value);
|
||||
if (!decoded.ok) {
|
||||
throw new TypeError(
|
||||
`Generated Service Worker asset manifest is invalid: ${decoded.error.reason}`,
|
||||
);
|
||||
}
|
||||
const expected = `sha256:${createHash("sha256")
|
||||
.update(canonicalStaticManifestBytes(decoded.manifest.assets))
|
||||
.digest("hex")}`;
|
||||
if (expected !== decoded.manifest.setDigest) {
|
||||
throw new TypeError(
|
||||
"Generated Service Worker asset manifest set digest does not match its assets.",
|
||||
);
|
||||
}
|
||||
return decoded.manifest as unknown as StaticAssetManifestV1;
|
||||
}
|
||||
|
||||
function record(value: unknown): Record<string, unknown> | null {
|
||||
return value && typeof value === "object" && !Array.isArray(value)
|
||||
? (value as Record<string, unknown>)
|
||||
: null;
|
||||
}
|
||||
@@ -0,0 +1,94 @@
|
||||
import { appendFile } from "node:fs/promises";
|
||||
|
||||
import {
|
||||
cleanupFinalizedPromotion,
|
||||
finalizeVerifiedPromotion,
|
||||
} from "./promotion-stager.ts";
|
||||
|
||||
export async function runStageVerifiedPromotionCli(
|
||||
environment: NodeJS.ProcessEnv,
|
||||
dependencies: Readonly<{
|
||||
cwd?: () => string;
|
||||
finalize?: typeof finalizeVerifiedPromotion;
|
||||
cleanup?: typeof cleanupFinalizedPromotion;
|
||||
appendOutput?: (path: string, content: string) => Promise<void>;
|
||||
writeStdout?: (content: string) => void;
|
||||
}> = {},
|
||||
): Promise<void> {
|
||||
const required = (name: string): string => {
|
||||
const value = environment[name];
|
||||
if (!value) throw new TypeError(`promotion staging environment is missing ${name}`);
|
||||
return value;
|
||||
};
|
||||
const attempt = Number(
|
||||
environment.GITEA_RUN_ATTEMPT ??
|
||||
environment.GITHUB_RUN_ATTEMPT ??
|
||||
required("CI_RUN_ATTEMPT"),
|
||||
);
|
||||
if (!Number.isInteger(attempt) || attempt < 1 || attempt > 1_000) {
|
||||
throw new TypeError("promotion staging run attempt is invalid");
|
||||
}
|
||||
const runnerTempRoot = required("RUNNER_TEMP");
|
||||
const staged = await (dependencies.finalize ?? finalizeVerifiedPromotion)({
|
||||
repositoryRoot: (dependencies.cwd ?? process.cwd)(),
|
||||
archivePath: required("CANDIDATE_ARCHIVE_PATH"),
|
||||
expectedArchiveSha256: required("CANDIDATE_ARCHIVE_SHA256"),
|
||||
vulnerabilityReportPath: required("VULNERABILITY_REPORT_PATH"),
|
||||
provenanceAttestationPath: required("PROVENANCE_ATTESTATION_PATH"),
|
||||
vulnerabilityPublicKeyPath: required("VULNERABILITY_PUBLIC_KEY_PATH"),
|
||||
vulnerabilityKeyId: required("VULNERABILITY_KEY_ID"),
|
||||
provenancePublicKeyPath: required("PROVENANCE_PUBLIC_KEY_PATH"),
|
||||
provenanceKeyId: required("PROVENANCE_KEY_ID"),
|
||||
expectedRun: {
|
||||
id:
|
||||
environment.GITEA_RUN_ID ??
|
||||
environment.GITHUB_RUN_ID ??
|
||||
required("CI_RUN_ID"),
|
||||
attempt,
|
||||
sourceRevision:
|
||||
environment.EXPECTED_SOURCE_REVISION ?? required("VITE_COMMIT_SHA"),
|
||||
},
|
||||
vulnerabilityInvocationNonce: required("VULNERABILITY_INVOCATION_NONCE"),
|
||||
provenanceInvocationNonce: required("PROVENANCE_INVOCATION_NONCE"),
|
||||
runnerTempRoot,
|
||||
});
|
||||
try {
|
||||
const output = required("GITHUB_OUTPUT");
|
||||
const content = [
|
||||
`staging_root=${staged.stagingRoot}`,
|
||||
`cleanup_token=${staged.cleanupToken}`,
|
||||
`runner_temp_dev=${staged.runnerTempIdentity.dev}`,
|
||||
`runner_temp_ino=${staged.runnerTempIdentity.ino}`,
|
||||
`staging_dev=${staged.stagingIdentity.dev}`,
|
||||
`staging_ino=${staged.stagingIdentity.ino}`,
|
||||
"",
|
||||
].join("\n");
|
||||
await (dependencies.appendOutput ?? defaultAppendOutput)(output, content);
|
||||
} catch (error) {
|
||||
try {
|
||||
await (dependencies.cleanup ?? cleanupFinalizedPromotion)({
|
||||
runnerTempRoot,
|
||||
stagingRoot: staged.stagingRoot,
|
||||
cleanupToken: staged.cleanupToken,
|
||||
runnerTempIdentity: staged.runnerTempIdentity,
|
||||
stagingIdentity: staged.stagingIdentity,
|
||||
});
|
||||
} catch (cleanupError) {
|
||||
throw new AggregateError(
|
||||
[error, cleanupError],
|
||||
"promotion output publication and direct staging cleanup both failed",
|
||||
{ cause: cleanupError },
|
||||
);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
(dependencies.writeStdout ?? process.stdout.write.bind(process.stdout))(
|
||||
`Promotion staging: ${staged.files
|
||||
.map(({ name, sha256 }) => `${name}=${sha256}`)
|
||||
.join(", ")} PASS\n`,
|
||||
);
|
||||
}
|
||||
|
||||
async function defaultAppendOutput(path: string, content: string): Promise<void> {
|
||||
await appendFile(path, content, { encoding: "utf8" });
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
export function deterministicSupplyChainGeneratedAt(input: Readonly<{
|
||||
generatedAt: string;
|
||||
sourceDateEpoch: string | null;
|
||||
}>): string {
|
||||
const generatedAtMs = Date.parse(input.generatedAt);
|
||||
if (!Number.isFinite(generatedAtMs)) {
|
||||
throw new TypeError("build manifest generatedAt must be an ISO timestamp");
|
||||
}
|
||||
if (input.sourceDateEpoch !== null) {
|
||||
if (!/^(?:0|[1-9]\d*)$/u.test(input.sourceDateEpoch)) {
|
||||
throw new TypeError("SOURCE_DATE_EPOCH must be whole seconds");
|
||||
}
|
||||
const epoch = Number(input.sourceDateEpoch);
|
||||
if (
|
||||
!Number.isSafeInteger(epoch) ||
|
||||
new Date(epoch * 1000).toISOString() !== input.generatedAt
|
||||
) {
|
||||
throw new TypeError(
|
||||
"build manifest generatedAt must match SOURCE_DATE_EPOCH",
|
||||
);
|
||||
}
|
||||
}
|
||||
return new Date(generatedAtMs).toISOString();
|
||||
}
|
||||
@@ -0,0 +1,535 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
function readProjectName(): string {
|
||||
const manifest: unknown = JSON.parse(
|
||||
readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
|
||||
);
|
||||
const name =
|
||||
typeof manifest === "object" && manifest !== null
|
||||
? (manifest as { name?: unknown }).name
|
||||
: undefined;
|
||||
if (typeof name !== "string" || name.length === 0) {
|
||||
throw new TypeError("package.json must declare a non-empty \"name\"");
|
||||
}
|
||||
return name;
|
||||
}
|
||||
|
||||
/**
|
||||
* Identity every release artifact is attributed to. A project derived from this
|
||||
* template renames itself by editing `name` in package.json and nothing else.
|
||||
*/
|
||||
export const PROJECT_NAME = readProjectName();
|
||||
|
||||
export type DependencyScope = "production" | "development";
|
||||
export type LockfilePackage = Readonly<{
|
||||
name: string;
|
||||
version: string;
|
||||
integrity: string;
|
||||
}>;
|
||||
export type DependencyInventoryRow = Readonly<{
|
||||
name: string;
|
||||
version: string;
|
||||
direct: boolean;
|
||||
scope: DependencyScope;
|
||||
optional: boolean;
|
||||
license: string;
|
||||
dependencies: readonly string[];
|
||||
}>;
|
||||
export type DependencyUpgrade = Readonly<{
|
||||
name: string;
|
||||
from: string;
|
||||
to: string;
|
||||
}>;
|
||||
export type DependencyInventoryDiff = Readonly<{
|
||||
added: readonly string[];
|
||||
removed: readonly string[];
|
||||
changed: readonly string[];
|
||||
upgrades: readonly DependencyUpgrade[];
|
||||
}>;
|
||||
|
||||
type MutableDependencyRecord = {
|
||||
name: string;
|
||||
version: string;
|
||||
direct: boolean;
|
||||
scope: DependencyScope;
|
||||
optional: boolean;
|
||||
packagePath: string;
|
||||
dependencies: Set<string>;
|
||||
};
|
||||
|
||||
type Document = Readonly<Record<string, unknown>>;
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function recordValue(value: unknown): Record<string, unknown> {
|
||||
return isRecord(value) ? value : {};
|
||||
}
|
||||
|
||||
function recordRows(value: unknown): Record<string, unknown>[] {
|
||||
return Array.isArray(value) ? value.filter(isRecord) : [];
|
||||
}
|
||||
|
||||
function stringRows(value: unknown): string[] {
|
||||
return Array.isArray(value)
|
||||
? value.filter((entry): entry is string => typeof entry === "string")
|
||||
: [];
|
||||
}
|
||||
|
||||
function dependencyIdentity(row: Readonly<Record<string, unknown>>): string {
|
||||
return `${String(row.name ?? "")}@${String(row.version ?? "")}`;
|
||||
}
|
||||
|
||||
export function canonicalizeSupplyChainValue(value: unknown): unknown {
|
||||
if (Array.isArray(value)) {
|
||||
return value
|
||||
.map(canonicalizeSupplyChainValue)
|
||||
.sort((left, right) =>
|
||||
String(JSON.stringify(left)).localeCompare(String(JSON.stringify(right))),
|
||||
);
|
||||
}
|
||||
if (isRecord(value)) {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, item]) => [key, canonicalizeSupplyChainValue(item)]),
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
export function supplyChainDigest(value: unknown): string {
|
||||
return createHash("sha256")
|
||||
.update(JSON.stringify(canonicalizeSupplyChainValue(value)))
|
||||
.digest("hex");
|
||||
}
|
||||
|
||||
export function parsePnpmLockfilePackages(
|
||||
lockfile: string,
|
||||
): LockfilePackage[] {
|
||||
const entries: LockfilePackage[] = [];
|
||||
let inPackages = false;
|
||||
let current: { name: string; version: string; integrity: string } | null = null;
|
||||
|
||||
for (const line of lockfile.split(/\r?\n/)) {
|
||||
if (line === "packages:") {
|
||||
inPackages = true;
|
||||
continue;
|
||||
}
|
||||
if (line === "snapshots:") {
|
||||
if (current) entries.push(current);
|
||||
break;
|
||||
}
|
||||
if (!inPackages) continue;
|
||||
const packageMatch = line.match(/^ {2}(\S.*):$/);
|
||||
if (packageMatch?.[1]) {
|
||||
if (current) entries.push(current);
|
||||
const key = packageMatch[1].replace(/^['"]|['"]$/g, "");
|
||||
const separator = key.lastIndexOf("@");
|
||||
current = {
|
||||
name: key.slice(0, separator),
|
||||
version: key.slice(separator + 1),
|
||||
integrity: "",
|
||||
};
|
||||
continue;
|
||||
}
|
||||
const integrityMatch = line.match(/\bintegrity:\s*([^,}\s]+)/);
|
||||
if (current && integrityMatch?.[1]) {
|
||||
current.integrity = integrityMatch[1];
|
||||
}
|
||||
}
|
||||
return entries.sort((left, right) =>
|
||||
`${left.name}@${left.version}`.localeCompare(
|
||||
`${right.name}@${right.version}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
export function isValidSha512Integrity(integrity: string): boolean {
|
||||
if (!integrity.startsWith("sha512-")) return false;
|
||||
try {
|
||||
return Buffer.from(integrity.slice("sha512-".length), "base64").length === 64;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function normalizeLicense(raw: unknown): string {
|
||||
if (typeof raw === "string" && raw.trim()) return raw.trim();
|
||||
if (isRecord(raw) && typeof raw.type === "string") return raw.type;
|
||||
if (Array.isArray(raw)) {
|
||||
const licenses = raw
|
||||
.map(normalizeLicense)
|
||||
.filter((license) => license !== "NOASSERTION");
|
||||
return licenses.length > 0 ? licenses.join(" OR ") : "NOASSERTION";
|
||||
}
|
||||
return "NOASSERTION";
|
||||
}
|
||||
|
||||
export async function flattenPnpmDependencyTree(
|
||||
root: Record<string, unknown>,
|
||||
directProduction: Readonly<Record<string, string>>,
|
||||
directDevelopment: Readonly<Record<string, string>>,
|
||||
): Promise<DependencyInventoryRow[]> {
|
||||
const records = new Map<string, MutableDependencyRecord>();
|
||||
const directIds = new Set<string>();
|
||||
|
||||
for (const [name, rawDependency] of Object.entries(
|
||||
recordValue(root.dependencies),
|
||||
)) {
|
||||
if (Object.hasOwn(directProduction, name) && isRecord(rawDependency)) {
|
||||
directIds.add(`${name}@${String(rawDependency.version ?? "")}`);
|
||||
}
|
||||
}
|
||||
for (const [name, rawDependency] of Object.entries(
|
||||
recordValue(root.devDependencies),
|
||||
)) {
|
||||
if (Object.hasOwn(directDevelopment, name) && isRecord(rawDependency)) {
|
||||
directIds.add(`${name}@${String(rawDependency.version ?? "")}`);
|
||||
}
|
||||
}
|
||||
|
||||
function visit(
|
||||
node: Record<string, unknown>,
|
||||
scope: DependencyScope,
|
||||
optionalPath: boolean,
|
||||
): void {
|
||||
const groups = {
|
||||
dependencies: node.dependencies,
|
||||
devDependencies: node.devDependencies,
|
||||
optionalDependencies: node.optionalDependencies,
|
||||
};
|
||||
for (const [groupName, group] of Object.entries(groups)) {
|
||||
for (const [name, rawDependency] of Object.entries(recordValue(group))) {
|
||||
if (!isRecord(rawDependency)) continue;
|
||||
const version = String(rawDependency.version ?? "");
|
||||
const packagePath = String(rawDependency.path ?? "");
|
||||
const identity = `${name}@${version}`;
|
||||
const childScope: DependencyScope =
|
||||
scope === "production" && groupName !== "devDependencies"
|
||||
? "production"
|
||||
: "development";
|
||||
const childOptional =
|
||||
optionalPath || groupName === "optionalDependencies";
|
||||
const previous = records.get(identity);
|
||||
const dependencies = previous?.dependencies ?? new Set<string>();
|
||||
for (const childGroup of [
|
||||
rawDependency.dependencies,
|
||||
rawDependency.optionalDependencies,
|
||||
]) {
|
||||
for (const [childName, rawChild] of Object.entries(
|
||||
recordValue(childGroup),
|
||||
)) {
|
||||
if (isRecord(rawChild)) {
|
||||
dependencies.add(
|
||||
`${childName}@${String(rawChild.version ?? "")}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
records.set(identity, {
|
||||
name,
|
||||
version,
|
||||
direct: directIds.has(identity),
|
||||
scope:
|
||||
previous?.scope === "production" || childScope === "production"
|
||||
? "production"
|
||||
: "development",
|
||||
optional: previous
|
||||
? previous.optional && childOptional
|
||||
: childOptional,
|
||||
packagePath: previous?.packagePath || packagePath,
|
||||
dependencies,
|
||||
});
|
||||
visit(rawDependency, childScope, childOptional);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const productionRoot: Record<string, unknown> = {
|
||||
dependencies: Object.fromEntries(
|
||||
Object.entries(recordValue(root.dependencies)).filter(([name]) =>
|
||||
Object.hasOwn(directProduction, name),
|
||||
),
|
||||
),
|
||||
};
|
||||
const developmentRoot: Record<string, unknown> = {
|
||||
devDependencies: Object.fromEntries(
|
||||
Object.entries(recordValue(root.devDependencies)).filter(([name]) =>
|
||||
Object.hasOwn(directDevelopment, name),
|
||||
),
|
||||
),
|
||||
};
|
||||
visit(productionRoot, "production", false);
|
||||
visit(developmentRoot, "development", false);
|
||||
|
||||
const result: DependencyInventoryRow[] = [];
|
||||
for (const record of records.values()) {
|
||||
let license = "NOASSERTION";
|
||||
let optional = record.optional;
|
||||
if (record.packagePath) {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(
|
||||
await readFile(`${record.packagePath}/package.json`, "utf8"),
|
||||
);
|
||||
const manifest = recordValue(parsed);
|
||||
license = normalizeLicense(manifest.license ?? manifest.licenses);
|
||||
} catch {
|
||||
// Platform-specific optional packages may not be materialized locally.
|
||||
optional = true;
|
||||
}
|
||||
}
|
||||
result.push({
|
||||
name: record.name,
|
||||
version: record.version,
|
||||
direct: record.direct,
|
||||
scope: record.scope,
|
||||
optional,
|
||||
license,
|
||||
dependencies: [...record.dependencies].sort(),
|
||||
});
|
||||
}
|
||||
return result.sort((left, right) =>
|
||||
`${left.name}@${left.version}`.localeCompare(
|
||||
`${right.name}@${right.version}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
export function diffDependencyInventories(
|
||||
before: Document,
|
||||
after: Document,
|
||||
): DependencyInventoryDiff {
|
||||
const beforeRows = recordRows(before.dependencies);
|
||||
const afterRows = recordRows(after.dependencies);
|
||||
const beforeMap = new Map(
|
||||
beforeRows.map((row) => [dependencyIdentity(row), row] as const),
|
||||
);
|
||||
const afterMap = new Map(
|
||||
afterRows.map((row) => [dependencyIdentity(row), row] as const),
|
||||
);
|
||||
const added = [...afterMap.keys()].filter((key) => !beforeMap.has(key));
|
||||
const removed = [...beforeMap.keys()].filter((key) => !afterMap.has(key));
|
||||
const changed: string[] = [];
|
||||
for (const key of [...beforeMap.keys()].filter((item) => afterMap.has(item))) {
|
||||
if (supplyChainDigest(beforeMap.get(key)) !== supplyChainDigest(afterMap.get(key))) {
|
||||
changed.push(key);
|
||||
}
|
||||
}
|
||||
const upgrades: DependencyUpgrade[] = [];
|
||||
for (const removedKey of removed) {
|
||||
const previous = beforeMap.get(removedKey);
|
||||
if (!previous) continue;
|
||||
const replacement = added.find(
|
||||
(addedKey) => afterMap.get(addedKey)?.name === previous.name,
|
||||
);
|
||||
const next = replacement ? afterMap.get(replacement) : undefined;
|
||||
if (next) {
|
||||
upgrades.push({
|
||||
name: String(previous.name ?? ""),
|
||||
from: String(previous.version ?? ""),
|
||||
to: String(next.version ?? ""),
|
||||
});
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
added: Object.freeze(added.sort()),
|
||||
removed: Object.freeze(removed.sort()),
|
||||
changed: Object.freeze(changed.sort()),
|
||||
upgrades: Object.freeze(
|
||||
upgrades.sort((left, right) => left.name.localeCompare(right.name)),
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
export function validateLicensePolicy(
|
||||
inventory: Document,
|
||||
policy: Document,
|
||||
) {
|
||||
const allowed = new Set(stringRows(policy.allowedLicenses));
|
||||
const denied = stringRows(policy.deniedLicensePatterns);
|
||||
const failures: string[] = [];
|
||||
const results: Array<Readonly<{
|
||||
package: string;
|
||||
license: string;
|
||||
passed: boolean;
|
||||
reason: string | null;
|
||||
}>> = [];
|
||||
for (const dependency of recordRows(inventory.dependencies)) {
|
||||
const license = String(dependency.license ?? "NOASSERTION");
|
||||
const explicitlyDenied = denied.some((pattern) =>
|
||||
new RegExp(pattern, "i").test(license),
|
||||
);
|
||||
const unknownAccepted =
|
||||
license === "NOASSERTION" && dependency.optional === true;
|
||||
const passed =
|
||||
!explicitlyDenied && (allowed.has(license) || unknownAccepted);
|
||||
results.push({
|
||||
package: dependencyIdentity(dependency),
|
||||
license,
|
||||
passed,
|
||||
reason: unknownAccepted ? "platform-optional-not-materialized" : null,
|
||||
});
|
||||
if (!passed) {
|
||||
failures.push(
|
||||
`${dependencyIdentity(dependency)} has disallowed license ${license}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0,
|
||||
failures: Object.freeze(failures),
|
||||
results: Object.freeze(results),
|
||||
});
|
||||
}
|
||||
|
||||
export function validateDependencyReview(
|
||||
diff: DependencyInventoryDiff,
|
||||
inventory: Document,
|
||||
evidenceFile: Document,
|
||||
) {
|
||||
const byIdentity = new Map(
|
||||
recordRows(inventory.dependencies).map(
|
||||
(row) => [dependencyIdentity(row), row] as const,
|
||||
),
|
||||
);
|
||||
const evidence = new Map<string, Record<string, unknown>>();
|
||||
for (const entry of recordRows(evidenceFile.changes)) {
|
||||
if (typeof entry.changeId === "string") evidence.set(entry.changeId, entry);
|
||||
}
|
||||
const highRisk = diff.added.filter((identity) => {
|
||||
const row = byIdentity.get(identity);
|
||||
return row?.direct === true && row.scope === "production";
|
||||
});
|
||||
const failures: string[] = [];
|
||||
for (const identity of highRisk) {
|
||||
const changeId = `add:${identity}`;
|
||||
const entry = evidence.get(changeId);
|
||||
if (!entry) {
|
||||
failures.push(`high-risk dependency missing review: ${changeId}`);
|
||||
continue;
|
||||
}
|
||||
for (const field of ["owner", "reviewer", "reason", "rollback"] as const) {
|
||||
const value = entry[field];
|
||||
if (typeof value !== "string" || !value.trim()) {
|
||||
failures.push(`${changeId} missing ${field}`);
|
||||
}
|
||||
}
|
||||
if (entry.owner === entry.reviewer) {
|
||||
failures.push(`${changeId} may not be self-approved`);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0,
|
||||
highRisk: Object.freeze(highRisk),
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
|
||||
const severityRank: ReadonlyMap<string, number> = new Map([
|
||||
["unknown", 0],
|
||||
["low", 1],
|
||||
["moderate", 2],
|
||||
["high", 3],
|
||||
["critical", 4],
|
||||
]);
|
||||
|
||||
export function validateVulnerabilityReport(
|
||||
report: Document,
|
||||
policy: Document,
|
||||
exceptionFile: Document,
|
||||
lockfileSha256: string,
|
||||
now: Date = new Date(),
|
||||
) {
|
||||
const failures: string[] = [];
|
||||
if (report.scannedLockfileSha256 !== lockfileSha256) {
|
||||
failures.push("vulnerability report lockfile digest mismatch");
|
||||
}
|
||||
if (typeof report.provider !== "string" || !report.provider.trim()) {
|
||||
failures.push("vulnerability report provider missing");
|
||||
}
|
||||
const threshold = severityRank.get(String(policy.blockAtSeverity)) ?? 3;
|
||||
const exceptions = recordRows(exceptionFile.exceptions);
|
||||
const blocking: string[] = [];
|
||||
for (const finding of recordRows(report.findings)) {
|
||||
const severity = String(finding.severity ?? "unknown").toLowerCase();
|
||||
if ((severityRank.get(severity) ?? 0) < threshold) continue;
|
||||
const exception = exceptions.find(
|
||||
(entry) =>
|
||||
entry.vulnerabilityId === finding.id &&
|
||||
entry.packageName === finding.packageName,
|
||||
);
|
||||
const expiry =
|
||||
typeof exception?.expiresAt === "string"
|
||||
? Date.parse(exception.expiresAt)
|
||||
: Number.NaN;
|
||||
const validException = Boolean(
|
||||
exception &&
|
||||
typeof exception.owner === "string" &&
|
||||
exception.owner.trim() &&
|
||||
typeof exception.reviewer === "string" &&
|
||||
exception.reviewer.trim() &&
|
||||
exception.owner !== exception.reviewer &&
|
||||
typeof exception.reason === "string" &&
|
||||
exception.reason.trim() &&
|
||||
Number.isFinite(expiry) &&
|
||||
expiry > now.getTime(),
|
||||
);
|
||||
if (!validException) {
|
||||
blocking.push(
|
||||
`${String(finding.id)}:${String(finding.packageName)}@${String(finding.version)}:${severity}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0 && blocking.length === 0,
|
||||
failures: Object.freeze(failures),
|
||||
blocking: Object.freeze(blocking),
|
||||
});
|
||||
}
|
||||
|
||||
export function verifySupplyChainCoherence(
|
||||
sbom: Document,
|
||||
inventory: Document,
|
||||
provenance: Document,
|
||||
distDigest: string,
|
||||
) {
|
||||
const failures: string[] = [];
|
||||
const componentCount = Array.isArray(sbom.components)
|
||||
? sbom.components.length
|
||||
: -1;
|
||||
const dependencyCount = Array.isArray(inventory.dependencies)
|
||||
? inventory.dependencies.length
|
||||
: -2;
|
||||
if (componentCount !== dependencyCount) {
|
||||
failures.push("SBOM component count does not match inventory");
|
||||
}
|
||||
const metadata = recordValue(sbom.metadata);
|
||||
const properties = recordRows(metadata.properties);
|
||||
if (
|
||||
properties.find(
|
||||
(property) =>
|
||||
property.name === "ca:lockfileSha256" &&
|
||||
property.value === inventory.lockfileSha256,
|
||||
) === undefined
|
||||
) {
|
||||
failures.push("SBOM lockfile digest does not match inventory");
|
||||
}
|
||||
const subject = recordRows(provenance.subject)[0];
|
||||
const subjectDigest = recordValue(subject?.digest);
|
||||
if (subjectDigest.sha256 !== distDigest) {
|
||||
failures.push("provenance subject does not match built dist digest");
|
||||
}
|
||||
const predicate = recordValue(provenance.predicate);
|
||||
const materials = recordValue(predicate.materials);
|
||||
if (materials.lockfileSha256 !== inventory.lockfileSha256) {
|
||||
failures.push("provenance lockfile material does not match inventory");
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import { z } from "zod";
|
||||
|
||||
export const testEvidenceReportSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(2),
|
||||
sourceRoot: z.string().min(1),
|
||||
status: z.enum(["PASS", "FAIL"]),
|
||||
facts: z
|
||||
.object({
|
||||
scannedFiles: z.number().int().nonnegative(),
|
||||
visualBaselines: z.number().int().nonnegative(),
|
||||
sharedScenarios: z.number().int().nonnegative(),
|
||||
declaredScenarioExecutions: z.number().int().nonnegative(),
|
||||
executedScenarioExecutions: z.number().int().nonnegative(),
|
||||
})
|
||||
.strict(),
|
||||
failures: z.array(z.string()),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((report, context) => {
|
||||
const passed = report.status === "PASS";
|
||||
if (passed !== (report.failures.length === 0)) {
|
||||
context.addIssue({ code: "custom", path: ["status"], message: "status must agree with failures" });
|
||||
}
|
||||
if (
|
||||
passed &&
|
||||
report.facts.declaredScenarioExecutions !==
|
||||
report.facts.executedScenarioExecutions
|
||||
) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["facts", "executedScenarioExecutions"],
|
||||
message: "PASS requires exact declared/executed scenario agreement",
|
||||
});
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,294 @@
|
||||
import { execFile } from "node:child_process";
|
||||
import {
|
||||
cp,
|
||||
mkdtemp,
|
||||
readFile,
|
||||
rm,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
const coverageMetrics = [
|
||||
"lines",
|
||||
"statements",
|
||||
"functions",
|
||||
"branches",
|
||||
] as const;
|
||||
const runtimeModule = "src/runtime.ts";
|
||||
const counterlessModules = Object.freeze([
|
||||
"src/import-empty.ts",
|
||||
"src/import-side-effect.ts",
|
||||
"src/import-type-empty.ts",
|
||||
"src/import-value.ts",
|
||||
"src/reexport-named.ts",
|
||||
"src/reexport-star.ts",
|
||||
"src/type-only.ts",
|
||||
] as const);
|
||||
const expectedModules = Object.freeze(
|
||||
[runtimeModule, ...counterlessModules].sort(),
|
||||
);
|
||||
const childOutputLimit = 1_800;
|
||||
|
||||
type ChildOutput = Readonly<{ stdout: string; stderr: string }>;
|
||||
type ChildInput = Readonly<{
|
||||
repositoryRoot: string;
|
||||
ownedRoot: string;
|
||||
configPath: string;
|
||||
}>;
|
||||
type CheckerOptions = Readonly<{
|
||||
repositoryRoot?: string;
|
||||
createOwnedRoot?: () => Promise<string>;
|
||||
runVitest?: (input: ChildInput) => Promise<ChildOutput>;
|
||||
}>;
|
||||
|
||||
export type V8CoverageCounterSemantics = Readonly<{
|
||||
counterBearingModules: readonly string[];
|
||||
counterlessModules: readonly string[];
|
||||
}>;
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function hasErrorCode(error: unknown, code: string): boolean {
|
||||
return isRecord(error) && error.code === code;
|
||||
}
|
||||
|
||||
function normalizeSummaryPath(value: string, fixtureRoot: string): string {
|
||||
const relative = path.isAbsolute(value) ? path.relative(fixtureRoot, value) : value;
|
||||
const normalized = relative.split(path.sep).join("/");
|
||||
if (
|
||||
normalized.length === 0 ||
|
||||
normalized === ".." ||
|
||||
normalized.startsWith("../") ||
|
||||
path.posix.isAbsolute(normalized)
|
||||
) {
|
||||
throw new TypeError(`V8 coverage row is outside the owned fixture: ${value}`);
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function coverageCounter(
|
||||
value: unknown,
|
||||
label: string,
|
||||
): Readonly<{ total: number; covered: number; skipped: number; pct: number }> {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
const { total, covered, skipped, pct } = value;
|
||||
if (
|
||||
typeof total !== "number" ||
|
||||
!Number.isSafeInteger(total) ||
|
||||
typeof covered !== "number" ||
|
||||
!Number.isSafeInteger(covered) ||
|
||||
typeof skipped !== "number" ||
|
||||
!Number.isSafeInteger(skipped) ||
|
||||
typeof pct !== "number" ||
|
||||
!Number.isFinite(pct) ||
|
||||
total < 0 ||
|
||||
covered < 0 ||
|
||||
skipped < 0 ||
|
||||
covered + skipped > total
|
||||
) {
|
||||
throw new TypeError(`${label} contains invalid coverage counters`);
|
||||
}
|
||||
const expectedPercentage =
|
||||
total === 0 ? 100 : Math.floor((covered / total) * 10_000) / 100;
|
||||
if (pct !== expectedPercentage) {
|
||||
throw new TypeError(`${label} contains invalid coverage counters`);
|
||||
}
|
||||
return { total, covered, skipped, pct };
|
||||
}
|
||||
|
||||
function coverageRow(
|
||||
value: unknown,
|
||||
label: string,
|
||||
): Readonly<Record<(typeof coverageMetrics)[number], ReturnType<typeof coverageCounter>>> {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
return Object.fromEntries(
|
||||
coverageMetrics.map((metric) => [
|
||||
metric,
|
||||
coverageCounter(value[metric], `${label}.${metric}`),
|
||||
]),
|
||||
) as Readonly<
|
||||
Record<(typeof coverageMetrics)[number], ReturnType<typeof coverageCounter>>
|
||||
>;
|
||||
}
|
||||
|
||||
export function assertV8CoverageCounterSemantics(
|
||||
value: unknown,
|
||||
fixtureRoot: string,
|
||||
): V8CoverageCounterSemantics {
|
||||
if (!isRecord(value)) throw new TypeError("V8 coverage summary must be an object");
|
||||
coverageRow(value.total, "V8 coverage total");
|
||||
const rows = new Map<string, ReturnType<typeof coverageRow>>();
|
||||
for (const [producerPath, producerRow] of Object.entries(value)) {
|
||||
if (producerPath === "total") continue;
|
||||
const normalizedPath = normalizeSummaryPath(producerPath, fixtureRoot);
|
||||
if (rows.has(normalizedPath)) {
|
||||
throw new TypeError(`V8 coverage row is duplicated: ${normalizedPath}`);
|
||||
}
|
||||
rows.set(
|
||||
normalizedPath,
|
||||
coverageRow(producerRow, `V8 coverage row ${normalizedPath}`),
|
||||
);
|
||||
}
|
||||
const actualModules = [...rows.keys()].sort();
|
||||
const missing = expectedModules.filter((modulePath) => !rows.has(modulePath));
|
||||
const additional = actualModules.filter(
|
||||
(modulePath) => !expectedModules.includes(modulePath),
|
||||
);
|
||||
if (missing.length > 0 || additional.length > 0) {
|
||||
throw new Error(
|
||||
`V8 coverage row set mismatch; missing: ${missing.join(", ") || "none"}; additional: ${additional.join(", ") || "none"}`,
|
||||
);
|
||||
}
|
||||
const runtimeRow = rows.get(runtimeModule)!;
|
||||
if (!coverageMetrics.some((metric) => runtimeRow[metric].total > 0)) {
|
||||
throw new Error(`V8 runtime module is not counter-bearing: ${runtimeModule}`);
|
||||
}
|
||||
for (const modulePath of counterlessModules) {
|
||||
const row = rows.get(modulePath)!;
|
||||
const exactAllZero = coverageMetrics.every((metric) => {
|
||||
const counter = row[metric];
|
||||
return (
|
||||
counter.total === 0 &&
|
||||
counter.covered === 0 &&
|
||||
counter.skipped === 0 &&
|
||||
counter.pct === 100
|
||||
);
|
||||
});
|
||||
if (!exactAllZero) {
|
||||
throw new Error(
|
||||
`V8 counterless module must have exact all-zero counters: ${modulePath}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
counterBearingModules: Object.freeze([runtimeModule]),
|
||||
counterlessModules: Object.freeze([...counterlessModules]),
|
||||
});
|
||||
}
|
||||
|
||||
function boundedChildOutput(value: unknown): string {
|
||||
const output =
|
||||
typeof value === "string"
|
||||
? value
|
||||
: value instanceof Uint8Array
|
||||
? new TextDecoder().decode(value)
|
||||
: "";
|
||||
if (output.length <= childOutputLimit) return output;
|
||||
return `${output.slice(0, childOutputLimit)}\n[truncated ${output.length - childOutputLimit} characters]`;
|
||||
}
|
||||
|
||||
async function defaultRunVitest(input: ChildInput): Promise<ChildOutput> {
|
||||
const result = await execFileAsync(
|
||||
process.execPath,
|
||||
[
|
||||
path.join(input.repositoryRoot, "node_modules/vitest/vitest.mjs"),
|
||||
"run",
|
||||
"--config",
|
||||
input.configPath,
|
||||
"--coverage",
|
||||
"--reporter=dot",
|
||||
"--no-color",
|
||||
],
|
||||
{
|
||||
cwd: input.ownedRoot,
|
||||
encoding: "utf8",
|
||||
timeout: 30_000,
|
||||
maxBuffer: 256 * 1024,
|
||||
},
|
||||
);
|
||||
return { stdout: result.stdout, stderr: result.stderr };
|
||||
}
|
||||
|
||||
function assertOwnedTemporaryRoot(value: string): string {
|
||||
const temporaryRoot = path.resolve(tmpdir());
|
||||
const ownedRoot = path.resolve(value);
|
||||
const relative = path.relative(temporaryRoot, ownedRoot);
|
||||
if (
|
||||
relative.length === 0 ||
|
||||
relative === ".." ||
|
||||
relative.startsWith(`..${path.sep}`) ||
|
||||
path.isAbsolute(relative)
|
||||
) {
|
||||
throw new TypeError(`V8 coverage fixture root is not an owned temp path: ${ownedRoot}`);
|
||||
}
|
||||
return ownedRoot;
|
||||
}
|
||||
|
||||
export async function checkV8CoverageCounterSemantics(
|
||||
options: CheckerOptions = {},
|
||||
): Promise<V8CoverageCounterSemantics> {
|
||||
const repositoryRoot = path.resolve(options.repositoryRoot ?? process.cwd());
|
||||
const createOwnedRoot =
|
||||
options.createOwnedRoot ??
|
||||
(() => mkdtemp(path.join(tmpdir(), "v8-counter-semantics-")));
|
||||
const runVitest = options.runVitest ?? defaultRunVitest;
|
||||
const ownedRoot = assertOwnedTemporaryRoot(await createOwnedRoot());
|
||||
const fixtureSource = path.join(
|
||||
repositoryRoot,
|
||||
"tests/fixtures/v8-coverage-counter-semantics",
|
||||
);
|
||||
const configPath = path.join(ownedRoot, "vitest.config.mjs");
|
||||
const reportsDirectory = path.join(ownedRoot, "coverage");
|
||||
try {
|
||||
await cp(fixtureSource, ownedRoot, { recursive: true });
|
||||
await writeFile(
|
||||
configPath,
|
||||
`export default ${JSON.stringify(
|
||||
{
|
||||
root: ownedRoot,
|
||||
test: {
|
||||
globals: true,
|
||||
include: ["counter-semantics.fixture.ts"],
|
||||
setupFiles: [],
|
||||
coverage: {
|
||||
provider: "v8",
|
||||
reportsDirectory,
|
||||
reporter: ["json-summary"],
|
||||
include: ["src/**/*.ts"],
|
||||
},
|
||||
},
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)};\n`,
|
||||
"utf8",
|
||||
);
|
||||
try {
|
||||
await runVitest({ repositoryRoot, ownedRoot, configPath });
|
||||
} catch (error) {
|
||||
const record = isRecord(error) ? error : {};
|
||||
throw new Error(
|
||||
`V8 coverage counter semantics child Vitest failed\nstdout:\n${boundedChildOutput(record.stdout)}\nstderr:\n${boundedChildOutput(record.stderr)}`,
|
||||
{ cause: error },
|
||||
);
|
||||
}
|
||||
const summaryPath = path.join(reportsDirectory, "coverage-summary.json");
|
||||
let summaryText: string;
|
||||
try {
|
||||
summaryText = await readFile(summaryPath, "utf8");
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) {
|
||||
throw new Error("V8 coverage counter semantics coverage summary is missing", {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
let summary: unknown;
|
||||
try {
|
||||
summary = JSON.parse(summaryText) as unknown;
|
||||
} catch (error) {
|
||||
throw new TypeError("V8 coverage counter semantics summary is invalid JSON", {
|
||||
cause: error,
|
||||
});
|
||||
}
|
||||
return assertV8CoverageCounterSemantics(summary, ownedRoot);
|
||||
} finally {
|
||||
await rm(ownedRoot, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user