@kungfu-tech/buildchain 3.0.2-alpha.4 → 3.0.2-alpha.6

package/scripts/generate-site-bundle.mjs

@@ -328,6 +328,7 @@ const manualMetaById = new Map(Object.entries({
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
+  "github-artifact-attestation": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 108 },
   "publication-authority": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 105 },
   "github-governance-authority": { capabilityGroup: "governance-versioning", audience: ["maintainer", "release-operator", "agent"], maturity: "preview", order: 106 },
   "controller-evidence": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator", "agent"], maturity: "draft", order: 205 },
@@ -405,6 +406,7 @@ function cliCommandMeta(id) {
     "collect-github-release": { group: "release-passport-trust", purpose: "Collect GitHub Release assets into a release passport." },
     create: { group: "release-passport-trust", purpose: "Create canonical sealed publication evidence documents." },
     "create-publication-admission": { group: "release-passport-trust", purpose: "Create a canonical short-lived publication admission envelope from exact consumer bindings." },
+    "create-github-artifact-attestation-policy": { group: "release-passport-trust", purpose: "Create an exact source, signer, Linux build, and Release Passport attestation policy." },
     "create-runner-provenance": { group: "release-passport-trust", purpose: "Create runner provenance evidence with an explicit qualification floor." },
     diagnostics: { group: "observability-diagnostics", purpose: "Inspect diagnostics command families." },
     "diagnostics-summary": { group: "observability-diagnostics", purpose: "Summarize diagnostics artifacts into JSON and cross-platform lifecycle timing tables." },
@@ -494,6 +496,7 @@ function cliCommandMeta(id) {
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
     "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
+    "verify-github-artifact-attestation": { group: "release-passport-trust", purpose: "Verify GitHub keyless attestation identity plus local artifact, manifest, Passport, predicate, bundle, and evidence bindings." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
     "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
     "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
@@ -532,6 +535,7 @@ function nodeApiMeta(exportName) {
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./anchored-version-material": { group: "reusable-build", summary: "Anchored/manual derived version material preflight, exact-tree binding, and digest evidence APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
+    "./github-artifact-attestation": { group: "release-passport-trust", summary: "GitHub keyless artifact attestation policy, predicate, provider evidence, and fail-closed verification APIs." },
     "./kfd-agent-hub": { group: "kfd-trust", summary: "Declarative Agent Hub adapter inspection, fixed-suite execution, exact KFD cut locking, and agent explanation APIs." },
     "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
@@ -606,6 +610,7 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
 }
 
 function workflowCapabilityGroup(entry) {
+  if (entry.id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
@@ -615,6 +620,7 @@ function workflowCapabilityGroup(entry) {
 }
 
 function actionCapabilityGroup(id) {
+  if (id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (id === "promote-buildchain-ref") return capabilityGroup("release-passport-trust");
   if (id === "run-lifecycle" || id === "validate-config") return capabilityGroup("reusable-build");
   if (id === "report-buildchain-issue") return capabilityGroup("observability-diagnostics");
@@ -898,6 +904,7 @@ function buildSiteBundle() {
         ["dev-pr-auto-merge", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
+        ["github-artifact-attestation", "release-passport"],
         ["buildchain-patrol", "repository-patrol"],
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
@@ -991,6 +998,7 @@ function buildSiteBundle() {
         "publish evidence JSON",
         "buildchain.release.json",
         "release passport assets",
+        "GitHub artifact attestation Sigstore bundle and Buildchain evidence JSON",
       ],
       owner: "promote-buildchain-ref",
     },
@@ -1023,6 +1031,10 @@ function buildSiteBundle() {
       "llms.txt",
       "buildchain-release-bundle.json",
       "buildchain-release-bundle.tar.gz",
+      "github-artifact-attestation.policy.json",
+      "github-artifact-attestation.predicate.json",
+      "github-artifact-attestation.evidence.json",
+      "attestation.sigstore.json",
     ],
     site: [
       "buildchain-site.json",

package/scripts/publish-github-artifact-attestation-evidence.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+import {
+  createGitHubArtifactAttestationVerificationPlan,
+  verifyGitHubArtifactAttestationEvidence,
+} from "../packages/core/github-artifact-attestation.js";
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!key?.startsWith("--") || value === undefined) throw new Error(`invalid argument near ${key || "<end>"}`);
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function sha256File(filePath) {
+  return `sha256:${sha256(fs.readFileSync(filePath))}`;
+}
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is not readable JSON: ${error.message}`);
+  }
+}
+
+function safeAssetStem(value) {
+  return path.basename(required(value, "subject name"))
+    .replace(/[^0-9A-Za-z._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+async function api({ token, apiUrl, route, method = "GET", headers = {}, body }) {
+  const response = await fetch(`${apiUrl}${route}`, {
+    method,
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "x-github-api-version": "2022-11-28",
+      ...headers,
+    },
+    body,
+  });
+  if (!response.ok) {
+    const detail = (await response.text()).slice(0, 500);
+    throw new Error(`GitHub API ${method} ${route} failed with ${response.status}: ${detail}`);
+  }
+  return response;
+}
+
+async function remoteAssetDigest({ token, apiUrl, repository, asset }) {
+  const declared = String(asset.digest || "").match(/^sha256:([0-9a-f]{64})$/i);
+  if (declared) return `sha256:${declared[1].toLowerCase()}`;
+  const response = await api({
+    token,
+    apiUrl,
+    route: `/repos/${repository}/releases/assets/${asset.id}`,
+    headers: { accept: "application/octet-stream" },
+  });
+  return `sha256:${sha256(Buffer.from(await response.arrayBuffer()))}`;
+}
+
+async function uploadImmutable({ token, apiUrl, repository, release, filePath, assetName }) {
+  const localDigest = sha256File(filePath);
+  const existing = (release.assets || []).filter((asset) => asset.name === assetName);
+  if (existing.length > 1) throw new Error(`release asset ${assetName} exists more than once`);
+  if (existing.length === 1) {
+    const remoteDigest = await remoteAssetDigest({ token, apiUrl, repository, asset: existing[0] });
+    if (remoteDigest !== localDigest) {
+      throw new Error(`immutable release asset collision for ${assetName}: ${remoteDigest} != ${localDigest}`);
+    }
+    return { action: "preserved", name: assetName, digest: localDigest, url: existing[0].browser_download_url };
+  }
+  const uploadBase = required(release.upload_url, "release.upload_url").replace(/\{.*$/, "");
+  const response = await fetch(`${uploadBase}?name=${encodeURIComponent(assetName)}`, {
+    method: "POST",
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "content-type": "application/octet-stream",
+      "x-github-api-version": "2022-11-28",
+    },
+    body: fs.readFileSync(filePath),
+  });
+  if (!response.ok) throw new Error(`GitHub release asset upload failed with ${response.status}: ${(await response.text()).slice(0, 500)}`);
+  const asset = await response.json();
+  release.assets = [...(release.assets || []), asset];
+  const remoteDigest = await remoteAssetDigest({ token, apiUrl, repository, asset });
+  if (remoteDigest !== localDigest) throw new Error(`release asset read-back mismatch for ${assetName}`);
+  return { action: "uploaded", name: assetName, digest: localDigest, url: asset.browser_download_url };
+}
+
+function appendOutput(name, value) {
+  if (process.env.GITHUB_OUTPUT) fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${String(value)}\n`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const token = required(process.env.GITHUB_TOKEN || process.env.GH_TOKEN, "GITHUB_TOKEN");
+  const apiUrl = (process.env.GITHUB_API_URL || "https://api.github.com").replace(/\/$/, "");
+  const repository = required(options.repository || process.env.GITHUB_REPOSITORY, "repository");
+  const tag = required(options.tag, "tag");
+  const subjectPath = path.resolve(required(options.subject, "subject"));
+  const manifestPath = path.resolve(required(options.manifest, "manifest"));
+  const passportPath = path.resolve(required(options.passport, "passport"));
+  const bundlePath = path.resolve(required(options.bundle, "bundle"));
+  const evidencePath = path.resolve(required(options.evidence, "evidence"));
+  const predicatePath = path.resolve(required(options.predicate, "predicate"));
+  const providerVerificationPath = path.resolve(required(options["provider-verification"], "provider-verification"));
+  const receiptPath = path.resolve(required(options.receipt, "receipt"));
+  const evidence = readJson(evidencePath, "Buildchain attestation evidence");
+  const plan = createGitHubArtifactAttestationVerificationPlan({ artifactPath: subjectPath, bundlePath, evidence });
+  const provider = spawnSync(plan.command, plan.args, { encoding: "utf8", env: process.env });
+  if (provider.status !== 0) throw new Error(`gh attestation verify failed: ${String(provider.stderr || provider.stdout).slice(0, 1000)}`);
+  const verificationResults = JSON.parse(provider.stdout);
+  const local = verifyGitHubArtifactAttestationEvidence({
+    artifactPath: subjectPath,
+    platformManifestPath: manifestPath,
+    releasePassportPath: passportPath,
+    bundlePath,
+    evidence,
+    verificationResults,
+  });
+  if (!local.ok) throw new Error(`Buildchain evidence verification failed: ${local.issues.map((issue) => issue.message).join("; ")}`);
+  const retainedProvider = readJson(providerVerificationPath, "retained provider verification");
+  const retained = verifyGitHubArtifactAttestationEvidence({
+    artifactPath: subjectPath,
+    platformManifestPath: manifestPath,
+    releasePassportPath: passportPath,
+    bundlePath,
+    evidence,
+    verificationResults: retainedProvider,
+  });
+  if (!retained.ok) {
+    throw new Error(`retained provider verification failed: ${retained.issues.map((issue) => issue.message).join("; ")}`);
+  }
+  const releaseResponse = await api({ token, apiUrl, route: `/repos/${repository}/releases/tags/${encodeURIComponent(tag)}` });
+  const release = await releaseResponse.json();
+  const stem = safeAssetStem(evidence.subject?.name);
+  const declarations = [
+    [bundlePath, `${stem}.sigstore-bundle.json`],
+    [evidencePath, `${stem}.buildchain-attestation.json`],
+    [predicatePath, `${stem}.buildchain-predicate.json`],
+    [providerVerificationPath, `${stem}.github-verification.json`],
+  ];
+  const assets = [];
+  for (const [filePath, assetName] of declarations) {
+    assets.push(await uploadImmutable({ token, apiUrl, repository, release, filePath, assetName }));
+  }
+  const receipt = {
+    contract: "buildchain.github-artifact-attestation-publication/v1",
+    repository,
+    tag,
+    releaseUrl: release.html_url,
+    subject: evidence.subject,
+    evidenceRoot: evidence.evidenceRoot,
+    attestation: evidence.attestation,
+    assets,
+    verified: true,
+  };
+  fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
+  fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  const receiptAsset = await uploadImmutable({
+    token,
+    apiUrl,
+    repository,
+    release,
+    filePath: receiptPath,
+    assetName: `${stem}.buildchain-attestation-publication.json`,
+  });
+  appendOutput("release-url", release.html_url);
+  appendOutput("evidence-root", evidence.evidenceRoot);
+  appendOutput("publication-receipt", receiptPath);
+  appendOutput("publication-receipt-digest", receiptAsset.digest);
+  process.stdout.write(`${JSON.stringify({ ...receipt, receiptAsset }, null, 2)}\n`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/release-candidate-resolver.mjs

@@ -608,6 +608,10 @@ export async function resolveReleaseCandidateArtifacts({
   }
   const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
   const platformManifestPaths = findDownloadedFiles(payloadDir, "manifest.json");
+  const githubArtifactAttestationPolicyPaths = findDownloadedFiles(
+    payloadDir,
+    "github-artifact-attestation-policy.json",
+  );
   const npmTarballPaths = publishArtifactKind === "npm"
     ? findDownloadedFilesByExtension(payloadDir, [".tgz"])
     : [];
@@ -639,6 +643,7 @@ export async function resolveReleaseCandidateArtifacts({
       buildSummary: outputPath(buildSummaryPath),
       payloads: outputPath(payloadDir),
       platformManifests: platformManifestPaths.map(outputPath),
+      githubArtifactAttestationPolicies: githubArtifactAttestationPolicyPaths.map(outputPath),
       npmTarballs: npmTarballPaths.map(outputPath),
       releaseAssets: releaseAssetPaths.map(outputPath),
       publishRequiredArtifacts: outputPath(requiredArtifactsPath),
@@ -647,6 +652,7 @@ export async function resolveReleaseCandidateArtifacts({
     candidateHash: passport.candidateHash || "",
     payloadCount: payloadArtifacts.length,
     platformManifestCount: platformManifestPaths.length,
+    githubArtifactAttestationPolicyCount: githubArtifactAttestationPolicyPaths.length,
     npmTarballCount: npmTarballPaths.length,
     publishRequiredArtifacts: generatedRequiredArtifacts,
   };
@@ -684,6 +690,12 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "release-candidate-payload-dir": result.paths?.payloads || "",
     "release-candidate-platform-manifest-paths": (result.paths?.platformManifests || []).join(","),
     "release-candidate-platform-manifest-count": String(result.platformManifestCount || 0),
+    "release-candidate-github-artifact-attestation-policy-paths": (
+      result.paths?.githubArtifactAttestationPolicies || []
+    ).join(","),
+    "release-candidate-github-artifact-attestation-policy-count": String(
+      result.githubArtifactAttestationPolicyCount || 0,
+    ),
     "release-candidate-npm-tarball-paths": (result.paths?.npmTarballs || []).join(","),
     "release-candidate-npm-tarball-count": String(result.npmTarballCount || 0),
     "release-candidate-github-release-artifact-paths": (

package/scripts/stage-github-artifact-attestation-inputs.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { stageGitHubArtifactAttestationInputs } from "../packages/core/github-artifact-attestation.js";
+
+function args(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!key?.startsWith("--") || value === undefined) {
+      throw new Error(`invalid argument near ${key || "<end>"}`);
+    }
+    values[key.slice(2)] = value;
+  }
+  return values;
+}
+
+function splitPaths(value) {
+  return String(value || "")
+    .split(/[\n,]/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function readPolicy(value) {
+  const candidate = path.resolve(String(value || ""));
+  return fs.existsSync(candidate)
+    ? JSON.parse(fs.readFileSync(candidate, "utf8"))
+    : JSON.parse(String(value || ""));
+}
+
+function appendOutput(name, value) {
+  const output = process.env.GITHUB_OUTPUT;
+  if (!output) return;
+  fs.appendFileSync(output, `${name}=${String(value)}\n`);
+}
+
+const options = args(process.argv.slice(2));
+const result = stageGitHubArtifactAttestationInputs({
+  policy: readPolicy(options.policy),
+  subjectRoots: splitPaths(options["subject-roots"]),
+  platformManifestPaths: splitPaths(options["platform-manifests"]),
+  releasePassportPath: options["release-passport"],
+  outputDir: options["output-dir"],
+});
+appendOutput("input-dir", result.outputDir);
+appendOutput("policy-json", result.policyJson);
+appendOutput("subject-relative-path", result.relativePaths.subject);
+appendOutput("platform-manifest-relative-path", result.relativePaths.platformManifest);
+appendOutput("release-passport-relative-path", result.relativePaths.releasePassport);
+appendOutput("source-sha", result.policy.caller.sourceSha);
+appendOutput("signer-sha", result.policy.signer.workflowDigest);
+appendOutput("buildchain-runtime-sha", result.policy.build.buildchainRuntimeSha);
+appendOutput("subject-name", result.policy.subject.name);
+process.stdout.write(`${JSON.stringify({
+  contract: result.contract,
+  subject: result.policy.subject,
+  caller: result.policy.caller,
+  signer: result.policy.signer,
+  paths: result.relativePaths,
+}, null, 2)}\n`);