@kungfu-tech/buildchain 2.14.18-alpha.1 → 2.14.18-alpha.11

package/scripts/generate-site-bundle.mjs

@@ -325,6 +325,7 @@ const manualMetaById = new Map(Object.entries({
   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 },
   "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 },
   "binary-distribution": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 110 },
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
@@ -385,6 +386,7 @@ function cliCommandMeta(id) {
   const map = new Map(Object.entries({
     audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
     "audit-publication-control-plane": { group: "release-passport-trust", purpose: "Read GitHub publication controls, bind provider-enforced npm identity, and emit a sanitized expiring receipt." },
+    "audit-github-governance": { group: "governance-versioning", purpose: "Read the managed GitHub zone, aggregate native protection and ownership, and emit sanitized fail-closed governance receipts." },
     badges: { group: "distribution-indexes", purpose: "Inspect README badge command families." },
     "badges-bundle": { group: "distribution-indexes", purpose: "Generate or verify the combined KFD and Release Passport badge bundle." },
     "badges-readme": { group: "distribution-indexes", purpose: "Generate or verify managed README badge blocks." },
@@ -408,6 +410,7 @@ function cliCommandMeta(id) {
     homebrew: { group: "distribution-indexes", purpose: "Inspect Homebrew distribution-index command families." },
     "homebrew-check": { group: "distribution-indexes", purpose: "Verify Homebrew tap metadata against upstream release passport evidence." },
     "homebrew-update-formula": { group: "distribution-indexes", purpose: "Generate Homebrew Formula metadata from upstream release passport evidence." },
+    "github-governance": { group: "governance-versioning", purpose: "Plan, apply, or roll back one root-bound GitHub branch-protection rollout after a frozen read-only inventory." },
     "infra-contract": { group: "governance-versioning", purpose: "Validate and publish provider-neutral infrastructure contract evidence." },
     init: { group: "getting-started", purpose: "Bootstrap a repository with Buildchain configuration and caller workflow files." },
     inspect: { group: "release-passport-trust", purpose: "Inspect release and artifact evidence command families." },
@@ -506,6 +509,7 @@ function nodeApiMeta(exportName) {
     "./publication-authority": { group: "release-passport-trust", summary: "Sealed publication authority registry, runner provenance, control-plane audit, admission, and independent verification APIs." },
     "./publication-control-plane-audit": { group: "release-passport-trust", summary: "Read-only publication control-plane snapshot evaluation APIs." },
     "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
+    "./github-governance-authority": { group: "governance-versioning", summary: "Fail-closed GitHub ownership, effective-policy, managed-zone admission, rollout-plan, and immutable receipt APIs." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./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." },
@@ -870,6 +874,7 @@ function buildSiteBundle() {
         ["paper-release", "reusable-build"],
         ["release-propagation", "release-propagation"],
         ["dev-pr-auto-merge", "dev-governance"],
+        ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
         ["buildchain-patrol", "repository-patrol"],
         ["buildchain-patrol-daily", "repository-patrol"],

package/scripts/installer-publication.mjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const INSTALLER_PUBLICATION_SCHEMA =
+  "kungfu.bootstrap-installer-publication/v1";
+export const INSTALLER_EVIDENCE_SCHEMA =
+  "kungfu-buildchain-installer-publication-evidence/v1";
+
+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 root(value) {
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function sha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function requireRoot(value, label) {
+  if (!/^sha256:[a-f0-9]{64}$/.test(value || "")) {
+    throw new Error(`${label} must be a sha256 root`);
+  }
+}
+
+function publicHttpsUrl(value, label) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${label} must be public HTTPS`);
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error(`${label} must be public HTTPS`);
+  }
+  return url;
+}
+
+function safeRelative(value, label) {
+  const normalized = String(value || "")
+    .replaceAll("\\", "/")
+    .replace(/^\/+/, "");
+  if (
+    !normalized ||
+    normalized.split("/").includes("..") ||
+    path.isAbsolute(normalized)
+  ) {
+    throw new Error(`${label} is not a safe relative path`);
+  }
+  return normalized;
+}
+
+function readAsset(artifactRoot, relativePath, expected) {
+  const safePath = safeRelative(relativePath, "installer asset path");
+  const absolute = path.resolve(artifactRoot, safePath);
+  const rootPath = path.resolve(artifactRoot);
+  if (
+    !absolute.startsWith(`${rootPath}${path.sep}`) ||
+    !fs.statSync(absolute).isFile()
+  ) {
+    throw new Error(`installer asset is missing: ${safePath}`);
+  }
+  const bytes = fs.readFileSync(absolute);
+  const observed = {
+    path: safePath,
+    size: bytes.length,
+    digest: sha256(bytes),
+  };
+  if (observed.size !== expected.size || observed.digest !== expected.digest) {
+    throw new Error(
+      `installer asset differs from publication metadata: ${safePath}`,
+    );
+  }
+  return observed;
+}
+
+export function validateInstallerPublication({ publication, artifactRoot }) {
+  if (publication?.schema !== INSTALLER_PUBLICATION_SCHEMA) {
+    throw new Error("unsupported installer publication schema");
+  }
+  if (!["alpha", "stable"].includes(publication.channel)) {
+    throw new Error("installer publication channel is invalid");
+  }
+  requireRoot(publication.channelPayloadRoot, "channelPayloadRoot");
+  requireRoot(publication.channelFileDigest, "channelFileDigest");
+  requireRoot(publication.releasePassport?.root, "releasePassport.root");
+  publicHttpsUrl(publication.channelUrl, "channelUrl");
+  if (!/^[a-f0-9]{40}$/.test(publication.sourceCommit || "")) {
+    throw new Error("installer publication sourceCommit is invalid");
+  }
+  const immutablePath = safeRelative(
+    publication.immutablePath,
+    "immutablePath",
+  );
+  if (publication.installerVersion !== "v1") {
+    throw new Error("installer publication version is unsupported");
+  }
+  if (!immutablePath.startsWith("installers/")) {
+    throw new Error("installer immutablePath must stay below installers/");
+  }
+  if (!publication.releasePassport?.ref) {
+    throw new Error("installer publication releasePassport.ref is required");
+  }
+  if (!Array.isArray(publication.entries) || publication.entries.length === 0) {
+    throw new Error("installer publication has no platform entries");
+  }
+  const identities = new Set();
+  for (const entry of publication.entries) {
+    const identity = `${entry.platform}/${entry.architecture}`;
+    if (identities.has(identity))
+      throw new Error(`duplicate installer target: ${identity}`);
+    identities.add(identity);
+    requireRoot(entry.manifestRoot, `${identity}.manifestRoot`);
+    requireRoot(entry.artifactRoot, `${identity}.artifactRoot`);
+    requireRoot(entry.artifactDigest, `${identity}.artifactDigest`);
+    publicHttpsUrl(entry.artifactUrl, `${identity}.artifactUrl`);
+    if (
+      entry.sourceCommit !== publication.sourceCommit ||
+      !entry.version ||
+      !Number.isSafeInteger(entry.artifactSize) ||
+      entry.artifactSize < 1 ||
+      !entry.artifactSignature
+    ) {
+      throw new Error(`installer target source mismatch: ${identity}`);
+    }
+  }
+  if (!Array.isArray(publication.assets) || publication.assets.length !== 2) {
+    throw new Error(
+      "installer publication must bind install.sh and install.ps1",
+    );
+  }
+  const expectedNames = new Set(["install.sh", "install.ps1"]);
+  const assets = publication.assets
+    .map((asset) => {
+      if (!expectedNames.delete(asset.name)) {
+        throw new Error(
+          `unexpected or duplicate installer asset: ${asset.name}`,
+        );
+      }
+      requireRoot(asset.digest, `${asset.name}.digest`);
+      if (!Number.isSafeInteger(asset.size) || asset.size < 1) {
+        throw new Error(`${asset.name}.size is invalid`);
+      }
+      const immutable = readAsset(
+        artifactRoot,
+        `${immutablePath}/${asset.name}`,
+        asset,
+      );
+      const friendly = readAsset(artifactRoot, asset.name, asset);
+      const friendlyUrl = publicHttpsUrl(
+        asset.friendlyUrl,
+        `${asset.name}.friendlyUrl`,
+      );
+      const immutableUrl = publicHttpsUrl(
+        asset.immutableUrl,
+        `${asset.name}.immutableUrl`,
+      );
+      if (
+        friendlyUrl.origin !== immutableUrl.origin ||
+        friendlyUrl.pathname !== `/${asset.name}` ||
+        immutableUrl.pathname !== `/${immutablePath}/${asset.name}`
+      ) {
+        throw new Error(
+          `installer asset URL mapping is invalid: ${asset.name}`,
+        );
+      }
+      return {
+        name: asset.name,
+        contentType: asset.contentType,
+        size: asset.size,
+        digest: asset.digest,
+        immutable,
+        friendly,
+        immutableUrl: immutableUrl.href,
+        friendlyUrl: friendlyUrl.href,
+      };
+    })
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const evidence = {
+    schema: INSTALLER_EVIDENCE_SCHEMA,
+    state: "verified",
+    installerVersion: publication.installerVersion,
+    channel: publication.channel,
+    sourceCommit: publication.sourceCommit,
+    channelPayloadRoot: publication.channelPayloadRoot,
+    channelFileDigest: publication.channelFileDigest,
+    releasePassport: publication.releasePassport,
+    immutablePath,
+    entries: publication.entries,
+    assets,
+  };
+  return { ...evidence, evidenceRoot: root(evidence) };
+}
+
+function cacheMaxAge(value) {
+  const match = /(?:^|,)\s*max-age=([0-9]+)(?:,|$)/i.exec(value || "");
+  return match ? Number(match[1]) : null;
+}
+
+async function readPublicAsset(url, fetchImpl) {
+  const response = await fetchImpl(url, {
+    redirect: "manual",
+    headers: { accept: "text/plain, application/octet-stream;q=0.9" },
+  });
+  if (response.status !== 200) {
+    throw new Error(
+      `installer public read-back failed (${response.status}): ${url}`,
+    );
+  }
+  return {
+    url,
+    bytes: Buffer.from(await response.arrayBuffer()),
+    contentType: response.headers.get("content-type") || "",
+    cacheControl: response.headers.get("cache-control") || "",
+    etag: response.headers.get("etag") || "",
+    versionId: response.headers.get("x-amz-version-id") || "",
+  };
+}
+
+export async function verifyInstallerPublicReadback({
+  publication,
+  fetchImpl = globalThis.fetch,
+}) {
+  if (typeof fetchImpl !== "function")
+    throw new Error("fetch implementation is required");
+  const observations = [];
+  for (const asset of publication.assets || []) {
+    for (const [route, url] of [
+      ["friendly", asset.friendlyUrl],
+      ["immutable", asset.immutableUrl],
+    ]) {
+      const observed = await readPublicAsset(url, fetchImpl);
+      const digest = sha256(observed.bytes);
+      if (observed.bytes.length !== asset.size || digest !== asset.digest) {
+        throw new Error(`installer public bytes drifted: ${url}`);
+      }
+      const contentType = observed.contentType.toLowerCase();
+      if (
+        !contentType.startsWith("text/plain") &&
+        !contentType.startsWith("text/x-shellscript") &&
+        !contentType.startsWith("application/octet-stream")
+      ) {
+        throw new Error(`installer public content type is unsafe: ${url}`);
+      }
+      const maxAge = cacheMaxAge(observed.cacheControl);
+      if (
+        route === "friendly" &&
+        (maxAge === null ||
+          maxAge > 300 ||
+          !/must-revalidate/i.test(observed.cacheControl))
+      ) {
+        throw new Error(
+          `friendly installer cache policy is not revalidated: ${url}`,
+        );
+      }
+      if (
+        route === "immutable" &&
+        (maxAge === null ||
+          maxAge < 31_536_000 ||
+          !/immutable/i.test(observed.cacheControl))
+      ) {
+        throw new Error(
+          `immutable installer cache policy is not immutable: ${url}`,
+        );
+      }
+      observations.push({
+        name: asset.name,
+        route,
+        url,
+        size: observed.bytes.length,
+        digest,
+        contentType: observed.contentType,
+        cacheControl: observed.cacheControl,
+        etag: observed.etag,
+        versionId: observed.versionId,
+      });
+    }
+  }
+  const evidence = {
+    schema: INSTALLER_EVIDENCE_SCHEMA,
+    state: "public-readback-verified",
+    sourceCommit: publication.sourceCommit,
+    channelPayloadRoot: publication.channelPayloadRoot,
+    releasePassport: publication.releasePassport,
+    observations,
+  };
+  return { ...evidence, evidenceRoot: root(evidence) };
+}
+
+function parseArgs(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--manifest") options.manifest = args[++index];
+    else if (value === "--artifact-root") options.artifactRoot = args[++index];
+    else if (value === "--public-readback") options.publicReadback = true;
+    else throw new Error(`unknown argument: ${value}`);
+  }
+  if (!options.manifest) throw new Error("--manifest is required");
+  if (!options.publicReadback && !options.artifactRoot) {
+    throw new Error("--artifact-root is required without --public-readback");
+  }
+  return options;
+}
+
+async function main(args) {
+  const options = parseArgs(args);
+  const publication = JSON.parse(
+    fs.readFileSync(path.resolve(options.manifest), "utf8"),
+  );
+  const evidence = options.publicReadback
+    ? await verifyInstallerPublicReadback({ publication })
+    : validateInstallerPublication({
+        publication,
+        artifactRoot: path.resolve(options.artifactRoot),
+      });
+  process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`installer-publication: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/publication-commit-evidence.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const SCHEMA = "kungfu-buildchain-publication-commit-evidence/v1";
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} is required`);
+  }
+  return value.trim();
+}
+
+function sha256Root(value, label) {
+  const normalized = requiredString(value, label);
+  if (!/^sha256:[0-9a-f]{64}$/.test(normalized)) {
+    throw new Error(`${label} must be a lowercase sha256 root`);
+  }
+  return normalized;
+}
+
+function exactSha(value, label) {
+  const normalized = requiredString(value, label);
+  if (!/^[0-9a-f]{40}$/.test(normalized)) {
+    throw new Error(`${label} must be an exact Git SHA`);
+  }
+  return normalized;
+}
+
+function publicHttps(value, label) {
+  const normalized = requiredString(value, label);
+  let url;
+  try {
+    url = new URL(normalized);
+  } catch {
+    throw new Error(`${label} must be a public HTTPS URL`);
+  }
+  if (
+    url.protocol !== "https:" ||
+    !url.hostname ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error(
+      `${label} must be a public HTTPS URL without credentials, query, or fragment`,
+    );
+  }
+  return normalized;
+}
+
+export function validatePublicationCommitEvidence(
+  evidence,
+  {
+    version,
+    sourceSha,
+    releaseSha,
+    releaseTag,
+  } = {},
+) {
+  if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
+    throw new Error("publication commit evidence must be an object");
+  }
+  if (evidence.schema !== SCHEMA) {
+    throw new Error(`publication commit evidence schema must be ${SCHEMA}`);
+  }
+  if (evidence.status !== "passed") {
+    throw new Error("publication commit evidence status must be passed");
+  }
+  const identity = evidence.identity || {};
+  const expected = {
+    version: requiredString(version, "expected version"),
+    sourceSha: exactSha(sourceSha, "expected sourceSha"),
+    releaseSha: exactSha(releaseSha, "expected releaseSha"),
+    releaseTag: requiredString(releaseTag, "expected releaseTag"),
+  };
+  for (const [field, value] of Object.entries(expected)) {
+    if (identity[field] !== value) {
+      throw new Error(`publication commit evidence ${field} mismatch`);
+    }
+  }
+  const publicUrl = publicHttps(evidence.publication?.url, "publication.url");
+  const payloadRoot = sha256Root(
+    evidence.publication?.payloadRoot,
+    "publication.payloadRoot",
+  );
+  if (
+    evidence.readback?.status !== "passed" ||
+    publicHttps(evidence.readback?.url, "readback.url") !== publicUrl ||
+    sha256Root(evidence.readback?.payloadRoot, "readback.payloadRoot") !==
+      payloadRoot
+  ) {
+    throw new Error(
+      "publication read-back must pass at the canonical URL with the exact payload root",
+    );
+  }
+  const previousAuthority = evidence.recovery?.previousAuthority;
+  const rollbackReference = requiredString(
+    evidence.recovery?.rollbackReference,
+    "recovery.rollbackReference",
+  );
+  if (!["preserved", "none"].includes(previousAuthority)) {
+    throw new Error(
+      "publication recovery must preserve or explicitly declare no previous authority",
+    );
+  }
+  return {
+    schema: SCHEMA,
+    status: "passed",
+    publicUrl,
+    payloadRoot,
+    identity: expected,
+    recovery: {
+      previousAuthority,
+      rollbackReference,
+    },
+  };
+}
+
+function main(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--evidence") options.evidence = args[++index];
+    else if (value === "--version") options.version = args[++index];
+    else if (value === "--source-sha") options.sourceSha = args[++index];
+    else if (value === "--release-sha") options.releaseSha = args[++index];
+    else if (value === "--release-tag") options.releaseTag = args[++index];
+    else throw new Error(`unknown argument: ${value}`);
+  }
+  const evidencePath = path.resolve(
+    requiredString(options.evidence, "--evidence"),
+  );
+  const result = validatePublicationCommitEvidence(
+    JSON.parse(fs.readFileSync(evidencePath, "utf8")),
+    options,
+  );
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(
+      `publication commit evidence failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    process.exit(1);
+  }
+}