@kungfu-tech/buildchain 2.14.18 → 2.14.19-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/release-candidate-resolver.mjs

@@ -402,7 +402,9 @@ export async function resolveReleaseCandidateArtifacts({
   const repoInfo = splitRepository(repository);
   const sha = assertSha(targetSha, "targetSha");
   const normalizedTarget = normalizeBranch(targetRef);
-  if (!/^(alpha|release)\/v\d+\/v\d+\.\d+$/.test(normalizedTarget)) {
+  const releaseCandidateTarget = /^(alpha|release)\/v\d+\/v\d+\.\d+$/.test(normalizedTarget);
+  const majorGateTarget = normalizedTarget === "publish-gate/major" || normalizedTarget === "major-gate";
+  if (!releaseCandidateTarget && !majorGateTarget) {
     return {
       enabled: false,
       reason: `target ref ${normalizedTarget || "(empty)"} does not require release-candidate promotion`,
@@ -414,14 +416,49 @@ export async function resolveReleaseCandidateArtifacts({
     fetchImpl,
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/commits/${sha}/pulls`,
   });
-  const pullRequest = selectMergedChannelPullRequest({
+  const channelPullRequest = selectMergedChannelPullRequest({
     pullRequests: Array.isArray(pulls) ? pulls : [],
     targetRef: normalizedTarget,
     repository: repoInfo.fullName,
   });
-  if (!pullRequest) {
+  if (!channelPullRequest) {
     throw new Error(`no same-repository merged channel PR found for ${sha} into ${normalizedTarget}`);
   }
+  let pullRequest = channelPullRequest;
+  if (majorGateTarget) {
+    const releaseRef = normalizeBranch(channelPullRequest.head?.ref || "");
+    if (!/^release\/v\d+\/v\d+\.\d+$/.test(releaseRef)) {
+      throw new Error(
+        `major gate ${normalizedTarget} must be merged from a release/vN/vN.M head, got ${releaseRef || "<empty>"}`,
+      );
+    }
+    const releaseSha = assertSha(channelPullRequest.head?.sha, "major gate release head SHA");
+    const releasePulls = await githubJson({
+      apiUrl,
+      token,
+      fetchImpl,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/commits/${releaseSha}/pulls`,
+    });
+    pullRequest = selectMergedChannelPullRequest({
+      pullRequests: Array.isArray(releasePulls) ? releasePulls : [],
+      targetRef: releaseRef,
+      repository: repoInfo.fullName,
+    });
+    if (!pullRequest) {
+      throw new Error(
+        `no same-repository merged release-candidate PR found for major gate release head ${releaseSha} into ${releaseRef}`,
+      );
+    }
+    const releaseMergeSha = assertSha(
+      pullRequest.merge_commit_sha || pullRequest.mergeCommit?.oid,
+      "release-candidate PR merge SHA",
+    );
+    if (releaseMergeSha !== releaseSha) {
+      throw new Error(
+        `major gate release head ${releaseSha} does not equal release-candidate PR #${pullRequest.number} merge ${releaseMergeSha}`,
+      );
+    }
+  }
   const timeoutMs = Number(waitSeconds) * 1000;
   const intervalMs = Number(pollIntervalMs);
   if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -501,6 +538,16 @@ export async function resolveReleaseCandidateArtifacts({
       headRef: pullRequest.head?.ref || "",
       baseRef: pullRequest.base?.ref || "",
     },
+    ...(majorGateTarget
+      ? {
+          promotionPullRequest: {
+            number: channelPullRequest.number,
+            url: channelPullRequest.html_url || channelPullRequest.url || "",
+            headRef: channelPullRequest.head?.ref || "",
+            baseRef: channelPullRequest.base?.ref || "",
+          },
+        }
+      : {}),
     run: {
       id: String(run.id || ""),
       url: run.html_url || run.url || "",