@kungfu-tech/buildchain 3.0.0 → 3.0.1-alpha.1

package/scripts/publication-commit-evidence.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 const SCHEMA = "kungfu-buildchain-publication-commit-evidence/v1";
+const INSTALLER_BUNDLE_SCHEMA = "kungfu.installer-publication-bundle/v1";
 
 function requiredString(value, label) {
   if (typeof value !== "string" || value.trim() === "") {
@@ -52,14 +54,194 @@ function publicHttps(value, label) {
   return normalized;
 }
 
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function digest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function semanticRoot(value) {
+  return digest(Buffer.from(JSON.stringify(canonical(value))));
+}
+
+function expectedContentType(assetPath) {
+  if (assetPath.endsWith(".json")) return "application/json; charset=utf-8";
+  if (assetPath.endsWith(".sh")) return "text/x-shellscript; charset=utf-8";
+  if (assetPath.endsWith(".ps1")) return "text/plain; charset=utf-8";
+  throw new Error(`installer bundle asset type is unsupported: ${assetPath}`);
+}
+
+function validateInstallerBundle(evidence, expected) {
+  const bundle = evidence.publication?.installerBundle;
+  if (!bundle) return null;
+  if (bundle.schema !== INSTALLER_BUNDLE_SCHEMA) {
+    throw new Error(
+      `installer bundle schema must be ${INSTALLER_BUNDLE_SCHEMA}`,
+    );
+  }
+  const bundleRoot = sha256Root(
+    bundle.bundleRoot,
+    "installerBundle.bundleRoot",
+  );
+  if (
+    bundleRoot !== evidence.publication.payloadRoot ||
+    bundleRoot !== evidence.readback?.payloadRoot
+  ) {
+    throw new Error(
+      "installer bundle root must be the publication payload root",
+    );
+  }
+  if (
+    exactSha(bundle.sourceCommit, "installerBundle.sourceCommit") !==
+      expected.sourceSha ||
+    !["alpha", "stable"].includes(bundle.channel)
+  ) {
+    throw new Error("installer bundle release identity mismatch");
+  }
+  sha256Root(bundle.channelPayloadRoot, "installerBundle.channelPayloadRoot");
+  sha256Root(bundle.channelFileDigest, "installerBundle.channelFileDigest");
+  sha256Root(
+    bundle.releasePassport?.root,
+    "installerBundle.releasePassport.root",
+  );
+  sha256Root(bundle.manifestDigest, "installerBundle.manifestDigest");
+  if (
+    evidence.readback?.manifestDigest !== bundle.manifestDigest ||
+    !Array.isArray(bundle.assets) ||
+    bundle.assets.length !== 7
+  ) {
+    throw new Error("installer bundle read-back or asset set is incomplete");
+  }
+  const paths = new Set();
+  const topLevel = new Set([
+    "installer-publication.json",
+    "channel-index.json",
+    "trusted-keys.json",
+    "install.sh",
+    "install.ps1",
+  ]);
+  const expectedRoles = new Map([
+    ["installer-publication.json", "publication-manifest"],
+    ["channel-index.json", "signed-channel-index"],
+    ["trusted-keys.json", "public-trust-anchors"],
+    ["install.sh", "friendly-installer"],
+    ["install.ps1", "friendly-installer"],
+  ]);
+  const immutableDirectories = new Set();
+  let immutableShell = 0;
+  let immutablePowerShell = 0;
+  const releaseBaseUrl =
+    `https://github.com/kungfu-systems/kungfu/releases/download/` +
+    expected.releaseTag;
+  for (const asset of bundle.assets) {
+    const assetPath = requiredString(
+      asset.path,
+      "installer bundle asset path",
+    ).replaceAll("\\", "/");
+    if (
+      assetPath.startsWith("/") ||
+      assetPath.endsWith("/") ||
+      assetPath.split("/").some((part) => part === "" || part === "..") ||
+      paths.has(assetPath)
+    ) {
+      throw new Error(
+        `unsafe or duplicate installer bundle asset: ${assetPath}`,
+      );
+    }
+    paths.add(assetPath);
+    topLevel.delete(assetPath);
+    if (assetPath.includes("/") && assetPath.endsWith("/install.sh")) {
+      immutableShell += 1;
+      immutableDirectories.add(path.posix.dirname(assetPath));
+    }
+    if (assetPath.includes("/") && assetPath.endsWith("/install.ps1")) {
+      immutablePowerShell += 1;
+      immutableDirectories.add(path.posix.dirname(assetPath));
+    }
+    if (!Number.isSafeInteger(asset.size) || asset.size < 1) {
+      throw new Error(`installer bundle asset size is invalid: ${assetPath}`);
+    }
+    sha256Root(asset.digest, `installer bundle asset digest: ${assetPath}`);
+    const releaseAsset = requiredString(
+      asset.releaseAsset,
+      `installer bundle release asset: ${assetPath}`,
+    );
+    if (
+      asset.contentType !== expectedContentType(assetPath) ||
+      publicHttps(
+        asset.releaseUrl,
+        `installer bundle asset URL: ${assetPath}`,
+      ) !== `${releaseBaseUrl}/${releaseAsset}` ||
+      !/^kungfu-[a-z0-9.-]+$/.test(releaseAsset)
+    ) {
+      throw new Error(
+        `installer bundle asset transport metadata is invalid: ${assetPath}`,
+      );
+    }
+    const expectedRole = assetPath.includes("/")
+      ? "immutable-installer"
+      : expectedRoles.get(assetPath);
+    if (asset.role !== expectedRole) {
+      throw new Error(`installer bundle asset role is invalid: ${assetPath}`);
+    }
+  }
+  const immutableDirectory = [...immutableDirectories][0] || "";
+  const immutableParts = immutableDirectory.split("/");
+  if (
+    topLevel.size !== 0 ||
+    immutableShell !== 1 ||
+    immutablePowerShell !== 1 ||
+    immutableDirectories.size !== 1 ||
+    immutableParts.length !== 5 ||
+    immutableParts[0] !== "installers" ||
+    immutableParts[1] !== "v1" ||
+    immutableParts[2] !== bundle.channel ||
+    immutableParts[3] !== expected.version ||
+    !/^[a-f0-9]{64}$/.test(immutableParts[4])
+  ) {
+    throw new Error("installer bundle asset topology is incomplete");
+  }
+  if (
+    bundle.cachePolicy?.friendly !== "public,max-age=300,must-revalidate" ||
+    bundle.cachePolicy?.immutable !== "public,max-age=31536000,immutable"
+  ) {
+    throw new Error("installer bundle cache policy is invalid");
+  }
+  if (
+    evidence.siteHandoff?.state !== "deferred-to-site-owned-consumer" ||
+    evidence.siteHandoff?.productionAvailable !== false ||
+    evidence.siteHandoff?.requiredBundleRoot !== bundleRoot
+  ) {
+    throw new Error("installer bundle site handoff must remain deferred");
+  }
+  return {
+    schema: bundle.schema,
+    bundleRoot,
+    manifestDigest: bundle.manifestDigest,
+    channel: bundle.channel,
+    channelPayloadRoot: bundle.channelPayloadRoot,
+    channelFileDigest: bundle.channelFileDigest,
+    releasePassport: bundle.releasePassport,
+    cachePolicy: bundle.cachePolicy,
+    immutablePath: immutableDirectory,
+    assets: bundle.assets,
+  };
+}
+
 export function validatePublicationCommitEvidence(
   evidence,
-  {
-    version,
-    sourceSha,
-    releaseSha,
-    releaseTag,
-  } = {},
+  { version, sourceSha, releaseSha, releaseTag } = {},
 ) {
   if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
     throw new Error("publication commit evidence must be an object");
@@ -107,6 +289,7 @@ export function validatePublicationCommitEvidence(
       "publication recovery must preserve or explicitly declare no previous authority",
     );
   }
+  const installerBundle = validateInstallerBundle(evidence, expected);
   return {
     schema: SCHEMA,
     status: "passed",
@@ -117,10 +300,109 @@ export function validatePublicationCommitEvidence(
       previousAuthority,
       rollbackReference,
     },
+    ...(installerBundle ? { installerBundle } : {}),
   };
 }
 
-function main(args) {
+export async function verifyInstallerBundleReadback(
+  result,
+  fetchImpl = globalThis.fetch,
+) {
+  const bundle = result.installerBundle;
+  if (!bundle) return null;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("installer bundle read-back requires fetch");
+  }
+  const manifestResponse = await fetchImpl(result.publicUrl, {
+    redirect: "manual",
+    cache: "no-store",
+  });
+  if (manifestResponse.status !== 200) {
+    throw new Error(
+      `installer bundle manifest read-back failed: HTTP ${manifestResponse.status}`,
+    );
+  }
+  const manifestBytes = Buffer.from(await manifestResponse.arrayBuffer());
+  if (digest(manifestBytes) !== bundle.manifestDigest) {
+    throw new Error("installer bundle manifest digest mismatch");
+  }
+  const manifest = JSON.parse(manifestBytes);
+  const unsigned = Object.fromEntries(
+    Object.entries(manifest).filter(([key]) => key !== "bundleRoot"),
+  );
+  if (
+    manifest.schema !== INSTALLER_BUNDLE_SCHEMA ||
+    manifest.bundleRoot !== bundle.bundleRoot ||
+    semanticRoot(unsigned) !== bundle.bundleRoot ||
+    manifest.package?.name !== "@kungfu-tech/site" ||
+    typeof manifest.package?.version !== "string" ||
+    manifest.identity?.sourceCommit !== result.identity.sourceSha ||
+    manifest.identity?.releaseSha !== result.identity.releaseSha ||
+    manifest.identity?.releaseTag !== result.identity.releaseTag ||
+    manifest.identity?.version !== result.identity.version ||
+    manifest.identity?.channel !== bundle.channel ||
+    manifest.identity?.channelPayloadRoot !== bundle.channelPayloadRoot ||
+    manifest.identity?.channelFileDigest !== bundle.channelFileDigest ||
+    manifest.identity?.releasePassport?.root !== bundle.releasePassport.root ||
+    manifest.distribution?.repository !== "kungfu-systems/kungfu" ||
+    manifest.routes?.immutablePath !== bundle.immutablePath ||
+    manifest.routes?.friendly?.["install.sh"] !==
+      "https://kungfu.tech/install.sh" ||
+    manifest.routes?.friendly?.["install.ps1"] !==
+      "https://kungfu.tech/install.ps1" ||
+    JSON.stringify(canonical(manifest.cachePolicy)) !==
+      JSON.stringify(canonical(bundle.cachePolicy)) ||
+    JSON.stringify(canonical(manifest.assets)) !==
+      JSON.stringify(canonical(bundle.assets)) ||
+    `${manifest.distribution?.releaseBaseUrl}/` +
+      manifest.distribution?.manifestAsset !==
+      result.publicUrl
+  ) {
+    throw new Error("installer bundle manifest root mismatch");
+  }
+  const observations = [];
+  const byUrl = new Map();
+  for (const asset of bundle.assets) {
+    let observation = byUrl.get(asset.releaseUrl);
+    if (!observation) {
+      const response = await fetchImpl(asset.releaseUrl, {
+        redirect: "manual",
+        cache: "no-store",
+      });
+      if (response.status !== 200) {
+        throw new Error(
+          `installer bundle asset read-back failed: HTTP ${response.status}`,
+        );
+      }
+      const bytes = Buffer.from(await response.arrayBuffer());
+      observation = {
+        releaseUrl: asset.releaseUrl,
+        size: bytes.length,
+        digest: digest(bytes),
+      };
+      byUrl.set(asset.releaseUrl, observation);
+    }
+    if (
+      observation.size !== asset.size ||
+      observation.digest !== asset.digest
+    ) {
+      throw new Error(`installer bundle asset drifted: ${asset.path}`);
+    }
+    observations.push({ path: asset.path, ...observation });
+  }
+  const seal = {
+    schema: "kungfu-buildchain-installer-publication-bundle-seal/v1",
+    bundleRoot: bundle.bundleRoot,
+    manifestDigest: bundle.manifestDigest,
+    sourceCommit: result.identity.sourceSha,
+    releaseTag: result.identity.releaseTag,
+    releasePassport: bundle.releasePassport,
+    observations,
+  };
+  return { ...seal, sealRoot: semanticRoot(seal) };
+}
+
+async function main(args) {
   const options = {};
   for (let index = 0; index < args.length; index += 1) {
     const value = args[index];
@@ -138,21 +420,25 @@ function main(args) {
     JSON.parse(fs.readFileSync(evidencePath, "utf8")),
     options,
   );
-  process.stdout.write(`${JSON.stringify(result)}\n`);
+  const installerBundleSeal = await verifyInstallerBundleReadback(result);
+  process.stdout.write(
+    `${JSON.stringify({
+      ...result,
+      ...(installerBundleSeal ? { installerBundleSeal } : {}),
+    })}\n`,
+  );
 }
 
 if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
 ) {
-  try {
-    main(process.argv.slice(2));
-  } catch (error) {
+  main(process.argv.slice(2)).catch((error) => {
     console.error(
       `publication commit evidence failed: ${
         error instanceof Error ? error.message : String(error)
       }`,
     );
     process.exit(1);
-  }
+  });
 }

package/scripts/resolve-artifact-coordinates.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import {
+  resolveArtifactContract,
+  writeGitHubOutputs,
+} from "./build-contract-core.mjs";
+
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error(`${label} is required`);
+  }
+  return normalized;
+}
+
+function parseArray(value, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error(`${label} must be valid JSON`);
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(`${label} must be a non-empty JSON array`);
+  }
+  return parsed;
+}
+
+export function resolveArtifactCoordinates({
+  artifacts,
+  platforms,
+  artifactName,
+  artifactNameTemplate,
+  sourceSha,
+  sourceRef = "",
+  repository,
+  runId,
+  runAttempt,
+  serverUrl = "https://github.com",
+}) {
+  if (!Array.isArray(artifacts)) {
+    throw new Error("artifacts must be an array");
+  }
+  if (!Array.isArray(platforms) || platforms.length === 0) {
+    throw new Error("platforms must be a non-empty array");
+  }
+  if (!SHA_PATTERN.test(sourceSha)) {
+    throw new Error("source SHA must be an exact lowercase commit SHA");
+  }
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
+    throw new Error("repository must be an owner/name coordinate");
+  }
+  if (!/^[1-9][0-9]*$/.test(String(runId))) {
+    throw new Error("run id must be a positive integer");
+  }
+  if (!/^[1-9][0-9]*$/.test(String(runAttempt))) {
+    throw new Error("run attempt must be a positive integer");
+  }
+
+  const coordinates = platforms.map((platform) => {
+    const id = required(platform?.id, "platform id");
+    const name = required(platform?.name, `platform ${id} name`);
+    const contract = resolveArtifactContract({
+      artifactName,
+      artifactNameTemplate,
+      platformId: id,
+      platformName: name,
+      sha: sourceSha,
+      ref: sourceRef,
+      runId: String(runId),
+      runAttempt: String(runAttempt),
+    });
+    const matches = artifacts.filter(
+      (artifact) =>
+        artifact?.name === contract.artifactName && !artifact.expired,
+    );
+    if (matches.length !== 1) {
+      throw new Error(
+        `expected exactly one live artifact named ${contract.artifactName}, found ${matches.length}`,
+      );
+    }
+    const artifact = matches[0];
+    if (!/^[1-9][0-9]*$/.test(String(artifact.id || ""))) {
+      throw new Error(`artifact ${contract.artifactName} has no exact id`);
+    }
+    if (!DIGEST_PATTERN.test(String(artifact.digest || ""))) {
+      throw new Error(`artifact ${contract.artifactName} has no exact digest`);
+    }
+    if (
+      !artifact.expires_at ||
+      !Number.isFinite(Date.parse(artifact.expires_at))
+    ) {
+      throw new Error(`artifact ${contract.artifactName} has no exact expiry`);
+    }
+    return {
+      platformId: id,
+      id: String(artifact.id),
+      name: artifact.name,
+      digest: artifact.digest,
+      url: `${serverUrl}/${repository}/actions/runs/${runId}/artifacts/${artifact.id}`,
+      expiresAt: new Date(artifact.expires_at).toISOString(),
+    };
+  });
+
+  coordinates.sort((left, right) =>
+    left.platformId.localeCompare(right.platformId),
+  );
+  return {
+    schema: "buildchain.github-artifact-coordinate-set/v1",
+    repository,
+    runId: String(runId),
+    runAttempt: String(runAttempt),
+    sourceSha,
+    artifacts: coordinates,
+  };
+}
+
+export function resolveArtifactCoordinatesCli(env = process.env) {
+  const artifactListPath = required(
+    env.BUILDCHAIN_ARTIFACT_LIST_PATH,
+    "BUILDCHAIN_ARTIFACT_LIST_PATH",
+  );
+  const outputPath = required(
+    env.BUILDCHAIN_ARTIFACT_COORDINATES_PATH,
+    "BUILDCHAIN_ARTIFACT_COORDINATES_PATH",
+  );
+  const artifacts = parseArray(
+    fs.readFileSync(artifactListPath, "utf8"),
+    "artifact list",
+  );
+  const platforms = parseArray(
+    env.BUILDCHAIN_PLATFORMS_JSON || "",
+    "platforms-json",
+  );
+  const result = resolveArtifactCoordinates({
+    artifacts,
+    platforms,
+    artifactName: env.BUILDCHAIN_ARTIFACT_NAME,
+    artifactNameTemplate: env.BUILDCHAIN_ARTIFACT_NAME_TEMPLATE,
+    sourceSha: env.BUILDCHAIN_SOURCE_SHA,
+    sourceRef: env.GITHUB_REF,
+    repository: env.GITHUB_REPOSITORY,
+    runId: env.GITHUB_RUN_ID,
+    runAttempt: env.GITHUB_RUN_ATTEMPT,
+    serverUrl: env.GITHUB_SERVER_URL,
+  });
+  const pretty = `${JSON.stringify(result, null, 2)}\n`;
+  const compact = JSON.stringify(result);
+  fs.writeFileSync(outputPath, pretty);
+  writeGitHubOutputs({
+    "artifact-coordinates-json": compact,
+    "artifact-coordinates-path": outputPath,
+  });
+  process.stdout.write(pretty);
+  return result;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    resolveArtifactCoordinatesCli();
+  } catch (error) {
+    console.error(`resolve-artifact-coordinates: ${error.message}`);
+    process.exitCode = 1;
+  }
+}