refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경

This commit is contained in:
donghyeon-ka
2026-09-24 00:42:21 +09:00
parent 91ae42a2a7
commit 6f6c48ebb7
1274 changed files with 290812 additions and 0 deletions
+70
View File
@@ -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"]);
+248
View File
@@ -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();
+143
View File
@@ -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`,
);
+49
View File
@@ -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",
);
+109
View File
@@ -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`,
);
+142
View File
@@ -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");
+58
View File
@@ -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");
+149
View File
@@ -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`,
);
+140
View File
@@ -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`,
);
+39
View File
@@ -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 });
}
+107
View File
@@ -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`,
);
+204
View File
@@ -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`,
);
+62
View File
@@ -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
);
}
+271
View File
@@ -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;
}
+43
View File
@@ -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" },
);
}
+697
View File
@@ -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`,
);
+108
View File
@@ -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();
+165
View File
@@ -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();
+185
View File
@@ -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();
}
+78
View File
@@ -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`,
);
+10
View File
@@ -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",
);
+151
View File
@@ -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");
+450
View File
@@ -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;
}
+29
View File
@@ -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");
+110
View File
@@ -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
+13
View File
@@ -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
+29
View File
@@ -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`,
);
+479
View File
@@ -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();
}
+131
View File
@@ -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;
}
}
+186
View File
@@ -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));
}
+498
View File
@@ -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;
}
}
+64
View File
@@ -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();
}
+376
View File
@@ -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();
}
+93
View File
@@ -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();
}
+153
View File
@@ -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();
}
+382
View File
@@ -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`,
);
+66
View File
@@ -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}`;
}
+96
View File
@@ -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);
}
+188
View File
@@ -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;
}
+742
View File
@@ -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})`);
}
+26
View File
@@ -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")! } : {}),
});
}
+679
View File
@@ -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;
}
}
+45
View File
@@ -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");
}
});
+187
View File
@@ -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);
}
+82
View File
@@ -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,
});
}
+49
View File
@@ -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()),
});
}
+353
View File
@@ -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;
}
+117
View File
@@ -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,
});
}
+31
View File
@@ -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");
}
}
+74
View 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 };
}
+281
View File
@@ -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")}`;
}
+24
View File
@@ -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,
});
}
}
+206
View File
@@ -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
+57
View File
@@ -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,
});
}
+373
View File
@@ -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);
}
+441
View File
@@ -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)];
}
+994
View File
@@ -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,
});
}
+36
View File
@@ -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 }));
}
+721
View File
@@ -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);
}
+209
View File
@@ -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");
}
+494
View File
@@ -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);
}
+763
View File
@@ -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));
}
+396
View File
@@ -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]);
}
+27
View File
@@ -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,
});
}
+103
View File
@@ -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);
}
+40
View File
@@ -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);
}
+641
View File
@@ -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);
}
+213
View File
@@ -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);
}
+163
View File
@@ -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>;
+42
View File
@@ -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;
}
}
+59
View File
@@ -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;
}
+138
View File
@@ -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;
}
+336
View File
@@ -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),
});
}
+261
View File
@@ -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;
}
+19
View File
@@ -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);
}
+85
View File
@@ -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),
});
}
+392
View File
@@ -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`),
]);
}
+327
View File
@@ -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()),
});
}
+346
View File
@@ -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;
}
}
+901
View File
@@ -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),
});
}
+283
View File
@@ -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);
}
+59
View File
@@ -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}/`),
),
),
);
}
+73
View File
@@ -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;
}
+170
View File
@@ -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);
}
}
+117
View File
@@ -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" });
}
+24
View File
@@ -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();
}
+535
View File
@@ -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),
});
}
+36
View File
@@ -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