@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.10

package/packages/core/v4-runtime-selector-persistence.js

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const V4_RUNTIME_PERSISTENCE_SCAN_CONTRACT =
+  "kungfu-buildchain-v4-runtime-persistence-scan/v1";
+
+const EXACT_SHA = /^[0-9a-f]{40}$/u;
+const TRAIN_V4_REF = /^train\/v4\/v4\.\d+\/[A-Za-z0-9._/-]+$/u;
+const AUTHORITY_V4_REF = /^authority\/v4\/v4\.\d+\/[A-Za-z0-9._/-]+$/u;
+const RUNTIME_SELECTOR =
+  /(?:buildchain[-_. ]?(?:ref|runtime)|runtime[-_. ]?sha|resume[-_. ]?buildchain)/iu;
+const EXACT_SHA_LITERAL = /\b[0-9a-f]{40}\b/giu;
+const EXTERNAL_AUTHORITY = Object.freeze([
+  ["oidc", /(?:id-token\s*:\s*write|oidc)/iu],
+  ["iam", /(?:role-to-assume|aws[-_. ]?(?:role|iam)|\biam\b)/iu],
+  ["repository-variable", /\$\{\{\s*vars\./u],
+  ["secret", /\$\{\{\s*secrets\./u],
+  ["environment", /\$\{\{\s*env\./u],
+]);
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function documentRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function normalizeRef(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^refs\/(?:heads|tags)\//u, "");
+}
+
+function transientSelector(value) {
+  const normalized = normalizeRef(value);
+  return (
+    EXACT_SHA.test(normalized.toLowerCase()) ||
+    TRAIN_V4_REF.test(normalized) ||
+    AUTHORITY_V4_REF.test(normalized) ||
+    /\$\{\{\s*(?:vars|secrets|env)\./u.test(value)
+  );
+}
+
+function listFiles(rootPath, relative, output) {
+  const directory = path.join(rootPath, relative);
+  if (!fs.existsSync(directory)) return;
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) listFiles(rootPath, child, output);
+    else if (entry.isFile() && /\.(?:json|toml|ya?ml)$/u.test(entry.name)) {
+      output.push(child.split(path.sep).join("/"));
+    }
+  }
+}
+
+function inputDefaultFailures(lines, sourcePath) {
+  const failures = [];
+  let current;
+  for (const [index, line] of lines.entries()) {
+    const key = line.match(/^(\s*)([a-z0-9-]+):\s*(?:#.*)?$/u);
+    if (key) {
+      const name = key[2];
+      if (RUNTIME_SELECTOR.test(name))
+        current = { indent: key[1].length, name };
+      else if (current && key[1].length <= current.indent) current = undefined;
+    }
+    if (!current) continue;
+    const defaultMatch = line.match(/^\s*default:\s*(.*?)\s*(?:#.*)?$/u);
+    if (!defaultMatch) continue;
+    const value = defaultMatch[1]
+      .replace(/^(?:["'])(.*)(?:["'])$/u, "$1")
+      .trim();
+    if (transientSelector(value)) {
+      failures.push({
+        code: "persistent-runtime-default",
+        path: sourcePath,
+        line: index + 1,
+        selector: current.name,
+      });
+    }
+  }
+  return failures;
+}
+
+function jsonSelectorFailures(value, sourcePath, trail = []) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) =>
+      jsonSelectorFailures(entry, sourcePath, [...trail, index]),
+    );
+  }
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, entry]) => {
+    const entryTrail = [...trail, key];
+    const selected =
+      (RUNTIME_SELECTOR.test(key) ||
+        trail.some((part) => RUNTIME_SELECTOR.test(String(part)))) &&
+      typeof entry === "string" &&
+      transientSelector(entry)
+        ? [
+            {
+              code: "persistent-runtime-json-value",
+              path: sourcePath,
+              jsonPointer: `/${entryTrail.map((part) => String(part).replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`,
+            },
+          ]
+        : [];
+    return [
+      ...selected,
+      ...jsonSelectorFailures(entry, sourcePath, entryTrail),
+    ];
+  });
+}
+
+function inspectSource({
+  resolvedRoot,
+  sourcePath,
+  files,
+  failures,
+  authorityUsage,
+}) {
+  const file = path.resolve(resolvedRoot, sourcePath);
+  if (!file.startsWith(`${resolvedRoot}${path.sep}`) || !fs.existsSync(file)) {
+    throw new Error(
+      `runtime persistence scan path is missing or escapes root: ${sourcePath}`,
+    );
+  }
+  const text = fs.readFileSync(file, "utf8");
+  const lines = text.split(/\r?\n/u);
+  files.push({ path: sourcePath, digest: documentRoot(text) });
+  failures.push(...inputDefaultFailures(lines, sourcePath));
+  if (sourcePath.endsWith(".json")) {
+    try {
+      failures.push(...jsonSelectorFailures(JSON.parse(text), sourcePath));
+    } catch (error) {
+      failures.push({
+        code: "runtime-selector-json-invalid",
+        path: sourcePath,
+        errorRoot: documentRoot(String(error?.message || error)),
+      });
+    }
+  }
+  for (const [index, line] of lines.entries()) {
+    if (RUNTIME_SELECTOR.test(line)) {
+      for (const match of line.matchAll(EXACT_SHA_LITERAL)) {
+        failures.push({
+          code: "persistent-runtime-exact-sha",
+          path: sourcePath,
+          line: index + 1,
+          selectorRoot: documentRoot(match[0].toLowerCase()),
+        });
+      }
+      if (/\$\{\{\s*(?:vars|secrets|env)\./u.test(line)) {
+        failures.push({
+          code: "persistent-runtime-external-indirection",
+          path: sourcePath,
+          line: index + 1,
+        });
+      }
+    }
+    for (const [authorityClass, pattern] of EXTERNAL_AUTHORITY) {
+      if (pattern.test(line)) {
+        authorityUsage.push({
+          class: authorityClass,
+          path: sourcePath,
+          line: index + 1,
+        });
+      }
+    }
+  }
+}
+
+export function scanV4RuntimeSelectorPersistence({
+  root: callerRoot = process.cwd(),
+  paths = undefined,
+} = {}) {
+  const resolvedRoot = path.resolve(callerRoot);
+  const sourcePaths = [];
+  if (paths) sourcePaths.push(...paths);
+  else {
+    for (const relative of [
+      ".github/workflows",
+      ".github/actions",
+      ".buildchain",
+    ]) {
+      listFiles(resolvedRoot, relative, sourcePaths);
+    }
+  }
+  const excluded = new Set([
+    ".buildchain/contract-lock.json",
+    ".buildchain/alpha-contract-lock.json",
+  ]);
+  const files = [];
+  const failures = [];
+  const authorityUsage = [];
+  for (const sourcePath of [...new Set(sourcePaths)].sort()) {
+    if (!excluded.has(sourcePath)) {
+      inspectSource({
+        resolvedRoot,
+        sourcePath,
+        files,
+        failures,
+        authorityUsage,
+      });
+    }
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: V4_RUNTIME_PERSISTENCE_SCAN_CONTRACT,
+    status: failures.length === 0 ? "passed" : "rejected",
+    files,
+    authorityUsage: authorityUsage.sort((left, right) =>
+      stableJson(left).localeCompare(stableJson(right)),
+    ),
+    failures: failures.sort((left, right) =>
+      stableJson(left).localeCompare(stableJson(right)),
+    ),
+  };
+  return { ...payload, root: documentRoot(payload) };
+}

package/packages/core/v4-tail-reseal-contract.js

@@ -0,0 +1,26 @@
+export const V4_TAIL_RESEAL_REQUEST_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-request/v1";
+export const V4_TAIL_RESEAL_PLAN_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-plan/v1";
+
+export const V4_TAIL_RESEAL_PLATFORMS = Object.freeze([
+  "linux-arm64",
+  "linux-x64",
+  "macos-arm64",
+  "windows-x64",
+]);
+
+export const V4_TAIL_RESEAL_PLATFORM_RUNNERS = Object.freeze({
+  "linux-arm64": '["ubuntu-24.04-arm"]',
+  "linux-x64": '["ubuntu-24.04"]',
+  "macos-arm64": '["macos-15"]',
+  "windows-x64": '["windows-2025"]',
+});
+
+export const V4_TAIL_RESEAL_REUSED_STAGE_KEYS = Object.freeze(
+  V4_TAIL_RESEAL_PLATFORMS.flatMap((platformId) =>
+    ["build", "install", "package", "verify"].map(
+      (stage) => `${platformId}:${stage}`,
+    ),
+  ).sort(),
+);

package/packages/core/v4-tail-reseal-github.js

@@ -0,0 +1,178 @@
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+import {
+  V4TailResealFault,
+  normalizeV4TailResealRequest,
+} from "./v4-tail-reseal.js";
+
+export const V4_TAIL_RESEAL_ADMISSION_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-admission/v1";
+
+const REQUIRED_SUCCESS_JOBS = Object.freeze([
+  "build / Linux ARM64",
+  "build / Linux x64",
+  "build / macOS ARM64",
+  "build / Windows x64",
+  "build / Control detached signing Linux ARM64",
+  "build / Control detached signing Linux x64",
+  "build / Control detached signing macOS ARM64",
+  "build / Control detached signing Windows x64",
+  "build / Finalize signed artifact Linux ARM64",
+  "build / Finalize signed artifact Linux x64",
+  "build / Finalize signed artifact Windows x64",
+]);
+
+function fault(code, path, message) {
+  throw new V4TailResealFault(code, path, message);
+}
+
+function exactArtifact(artifacts, name, digest, path) {
+  const matches = artifacts.filter((artifact) => artifact.name === name);
+  if (matches.length !== 1)
+    fault(
+      "tail-reseal-artifact-ambiguous",
+      path,
+      "retained artifact must resolve exactly once",
+    );
+  const artifact = matches[0];
+  if (artifact.expired === true)
+    fault("tail-reseal-retention-expired", path, "retained artifact expired");
+  if (artifact.digest !== digest)
+    fault(
+      "tail-reseal-artifact-archive-mismatch",
+      path,
+      "GitHub artifact archive digest drifted",
+    );
+  return artifact;
+}
+
+function validateSourceIdentity(normalized, sourceCommit, sourceRun) {
+  if (
+    sourceCommit?.sha !== normalized.source.sha ||
+    sourceCommit?.tree?.sha !== normalized.source.treeSha
+  )
+    fault(
+      "tail-reseal-source-mismatch",
+      "$/sourceCommit",
+      "source commit or tree readback drifted",
+    );
+  const workflowFile = String(sourceRun?.path || "")
+    .split("@")[0]
+    .replace(/^\.github\/workflows\//u, "");
+  if (
+    Number(sourceRun?.id) !== normalized.source.runId ||
+    Number(sourceRun?.run_attempt) !== normalized.source.runAttempt ||
+    sourceRun?.event !== "workflow_dispatch" ||
+    sourceRun?.status !== "completed" ||
+    sourceRun?.conclusion !== "failure" ||
+    sourceRun?.head_sha !== normalized.source.sha ||
+    workflowFile !== normalized.source.workflowFile ||
+    sourceRun?.name !== normalized.source.workflowName
+  )
+    fault(
+      "tail-reseal-source-run-mismatch",
+      "$/sourceRun",
+      "source run is not the exact retained failed Build run",
+    );
+}
+
+function validateSourceJobs(normalized, sourceJobs) {
+  const jobs = Array.isArray(sourceJobs) ? sourceJobs : [];
+  const byName = new Map(jobs.map((job) => [job.name, job]));
+  for (const name of REQUIRED_SUCCESS_JOBS)
+    if (byName.get(name)?.conclusion !== "success")
+      fault(
+        "tail-reseal-prior-stage-mismatch",
+        "$/sourceJobs",
+        `required source job did not succeed: ${name}`,
+      );
+  const failedJob = jobs.find(
+    (job) => Number(job.id) === normalized.failure.jobId,
+  );
+  const failedSteps = (failedJob?.steps || [])
+    .filter((step) => step.conclusion === "failure")
+    .map((step) => step.name);
+  if (
+    failedJob?.name !== normalized.failure.jobName ||
+    failedJob?.conclusion !== "failure" ||
+    JSON.stringify(failedSteps) !==
+      JSON.stringify([normalized.failure.stepName])
+  )
+    fault(
+      "tail-reseal-failure-mismatch",
+      "$/sourceJobs",
+      "observed failure is not the single authorized macOS tail failure",
+    );
+}
+
+function validateRetainedArtifacts(normalized, sourceArtifacts) {
+  for (const [index, platform] of normalized.platforms.entries()) {
+    exactArtifact(
+      sourceArtifacts || [],
+      platform.artifactName,
+      platform.artifactArchiveRoot,
+      `$/sourceArtifacts/${index}/payload`,
+    );
+    exactArtifact(
+      sourceArtifacts || [],
+      platform.manifestArtifactName,
+      platform.manifestArchiveRoot,
+      `$/sourceArtifacts/${index}/manifest`,
+    );
+  }
+}
+
+function validateSigningAuthority(normalized, signingRun, signingArtifacts) {
+  if (
+    Number(signingRun?.id) !== normalized.signing.authorityRunId ||
+    signingRun?.status !== "completed" ||
+    signingRun?.conclusion !== "success" ||
+    signingRun?.head_sha !== normalized.signing.runtimeSha
+  )
+    fault(
+      "tail-reseal-signer-authority-mismatch",
+      "$/signingRun",
+      "signing authority run readback drifted",
+    );
+  exactArtifact(
+    signingArtifacts || [],
+    normalized.signing.resultArtifact,
+    normalized.signing.resultArtifactRoot,
+    "$/signingArtifacts/result",
+  );
+}
+
+export function validateV4TailResealGitHubEvidence({
+  request,
+  sourceCommit,
+  sourceRun,
+  sourceJobs,
+  sourceArtifacts,
+  signingRun,
+  signingArtifacts,
+} = {}) {
+  const normalized = normalizeV4TailResealRequest(request);
+  validateSourceIdentity(normalized, sourceCommit, sourceRun);
+  validateSourceJobs(normalized, sourceJobs);
+  validateRetainedArtifacts(normalized, sourceArtifacts);
+  validateSigningAuthority(normalized, signingRun, signingArtifacts);
+  const payload = {
+    schema: V4_TAIL_RESEAL_ADMISSION_CONTRACT,
+    repository: normalized.repository,
+    sourceRoot: normalized.source.sourceRoot,
+    sourceRunId: normalized.source.runId,
+    signingAuthorityRunId: normalized.signing.authorityRunId,
+    retainedArchiveRoots: normalized.platforms.flatMap((platform) => [
+      platform.artifactArchiveRoot,
+      platform.manifestArchiveRoot,
+    ]),
+    priorFailureRoot: normalized.failure.evidenceRoot,
+    retentionReadbackRoot: normalized.retention.readbackRoot,
+    warrantReadbackRoot: normalized.warrant.stateReadbackRoot,
+  };
+  return {
+    ...payload,
+    admissionRoot: v4ContentRoot("tail-reseal-admission", payload),
+  };
+}
+
+export { REQUIRED_SUCCESS_JOBS as V4_TAIL_RESEAL_REQUIRED_SUCCESS_JOBS };

package/packages/core/v4-tail-reseal-receipt.js

@@ -0,0 +1,225 @@
+import { v4ContentRoot, validateV4Root } from "./v4-canonical-contracts.js";
+import { validateReleaseCandidatePassport } from "./release-candidate.js";
+import {
+  V4_TAIL_RESEAL_PLAN_CONTRACT,
+  V4_TAIL_RESEAL_PLATFORMS,
+  V4TailResealFault,
+  normalizeV4TailResealRequest,
+  planV4TailReseal,
+} from "./v4-tail-reseal.js";
+
+export const V4_TAIL_RESEAL_RECEIPT_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-receipt/v1";
+
+function fault(code, path, message) {
+  throw new V4TailResealFault(code, path, message);
+}
+
+function root(value, path) {
+  try {
+    validateV4Root(value, path);
+  } catch (error) {
+    fault("invalid-tail-reseal-root", path, error.message);
+  }
+  return value;
+}
+
+function exactKeys(value, expected, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fault("invalid-tail-reseal-shape", path, "object required");
+  const actual = Object.keys(value).sort();
+  const canonical = [...expected].sort();
+  if (
+    actual.length !== canonical.length ||
+    actual.some((key, index) => key !== canonical[index])
+  )
+    fault(
+      "invalid-tail-reseal-shape",
+      path,
+      "keys do not match the closed tail-reseal contract",
+    );
+}
+
+function positiveInteger(value, path) {
+  if (!Number.isSafeInteger(value) || value < 1)
+    fault(
+      "invalid-tail-reseal-integer",
+      path,
+      "positive safe integer required",
+    );
+}
+
+function validateReadbacks(readbacks, request) {
+  if (
+    !Array.isArray(readbacks) ||
+    readbacks.length !== V4_TAIL_RESEAL_PLATFORMS.length
+  )
+    fault(
+      "tail-reseal-readback-mismatch",
+      "$/readbacks",
+      "one readback per platform required",
+    );
+  const normalized = [...readbacks].sort((left, right) =>
+    Buffer.from(left.platformId || "").compare(
+      Buffer.from(right.platformId || ""),
+    ),
+  );
+  for (const [index, readback] of normalized.entries()) {
+    const path = `$/readbacks/${index}`;
+    exactKeys(
+      readback,
+      [
+        "platformId",
+        "artifactRoot",
+        "manifestRoot",
+        "capsuleRoot",
+        "byteIdentical",
+        "providerReadbackRoot",
+      ],
+      path,
+    );
+    const expected = request.platforms[index];
+    if (readback.platformId !== expected.id)
+      fault(
+        "tail-reseal-platform-mismatch",
+        `${path}/platformId`,
+        "unexpected platform readback",
+      );
+    for (const field of ["artifactRoot", "manifestRoot", "capsuleRoot"])
+      root(readback[field], `${path}/${field}`);
+    if (readback.capsuleRoot !== expected.capsuleRoot)
+      fault(
+        "tail-reseal-capsule-mismatch",
+        `${path}/capsuleRoot`,
+        "Stage Capsule identity changed during tail execution",
+      );
+    if (readback.platformId === "macos-arm64") {
+      if (readback.byteIdentical !== false)
+        fault(
+          "tail-reseal-macos-effect-missing",
+          `${path}/byteIdentical`,
+          "macOS signed bytes must be independently resealed",
+        );
+      root(readback.providerReadbackRoot, `${path}/providerReadbackRoot`);
+    } else if (
+      readback.byteIdentical !== true ||
+      readback.artifactRoot !== expected.artifactRoot ||
+      readback.manifestRoot !== expected.manifestRoot ||
+      readback.providerReadbackRoot !== null
+    )
+      fault(
+        "tail-reseal-nontail-byte-drift",
+        path,
+        "non-macOS retained artifacts must remain byte-identical and effect-free",
+      );
+  }
+  return normalized;
+}
+
+export function createV4TailResealReceipt({
+  request,
+  plan,
+  readbacks,
+  passport,
+  protectedReadbackRoot,
+  currentRun,
+} = {}) {
+  const normalized = normalizeV4TailResealRequest(request);
+  const expectedPlan = planV4TailReseal(normalized);
+  const { planRoot: _planRoot, ...planBody } = plan || {};
+  if (
+    plan?.schema !== V4_TAIL_RESEAL_PLAN_CONTRACT ||
+    plan.planRoot !== expectedPlan.planRoot ||
+    v4ContentRoot("tail-reseal-plan", planBody) !== expectedPlan.planRoot
+  )
+    fault(
+      "tail-reseal-plan-drift",
+      "$/plan",
+      "plan does not match the exact request",
+    );
+  const platformReadbacks = validateReadbacks(readbacks, normalized);
+  const passportValidation = validateReleaseCandidatePassport({
+    passport,
+    repository: normalized.repository,
+    targetChannel: normalized.target.channel,
+    version: normalized.target.version,
+    sourceHeadSha: normalized.source.sha,
+    requirePlatforms: true,
+  });
+  if (!passportValidation.ok)
+    fault(
+      "tail-reseal-passport-invalid",
+      "$/passport",
+      passportValidation.errors.join("; "),
+    );
+  if (
+    passport.contract !== "kungfu-buildchain-release-candidate-passport" ||
+    passport.buildchain?.sha !== normalized.runtime.sha ||
+    passport.consumerPolicy?.receiptRoot !==
+      normalized.runtime.consumerPolicyReceiptRoot
+  )
+    fault(
+      "tail-reseal-passport-binding-mismatch",
+      "$/passport",
+      "standard v4 candidate Passport bindings drifted",
+    );
+  root(protectedReadbackRoot, "$/protectedReadbackRoot");
+  exactKeys(currentRun, ["id", "attempt"], "$/currentRun");
+  positiveInteger(currentRun.id, "$/currentRun/id");
+  positiveInteger(currentRun.attempt, "$/currentRun/attempt");
+  const payload = {
+    schema: V4_TAIL_RESEAL_RECEIPT_CONTRACT,
+    action: "reused-retained-tail",
+    repository: normalized.repository,
+    source: normalized.source,
+    target: normalized.target,
+    runtime: normalized.runtime,
+    planRoot: expectedPlan.planRoot,
+    warrant: normalized.warrant,
+    retention: normalized.retention,
+    originalFailure: normalized.failure,
+    signingAuthority: normalized.signing,
+    releaseTail: normalized.releaseTail,
+    platformReadbacks,
+    skippedStages: expectedPlan.skippedStages,
+    rerunStages: expectedPlan.rerunStages,
+    passport: {
+      contract: passport.contract,
+      candidateHash: passport.candidateHash,
+      passportRoot: v4ContentRoot("release-candidate-passport", passport),
+    },
+    protectedReadbackRoot,
+    currentRun,
+  };
+  return {
+    ...payload,
+    receiptRoot: v4ContentRoot("tail-reseal-receipt", payload),
+  };
+}
+
+export function verifyV4TailResealReceipt({ receipt, request, passport } = {}) {
+  try {
+    const expected = createV4TailResealReceipt({
+      request,
+      plan: planV4TailReseal(request),
+      readbacks: receipt.platformReadbacks,
+      passport,
+      protectedReadbackRoot: receipt.protectedReadbackRoot,
+      currentRun: receipt.currentRun,
+    });
+    return {
+      ok: expected.receiptRoot === receipt.receiptRoot,
+      receiptRoot: expected.receiptRoot,
+      failures:
+        expected.receiptRoot === receipt.receiptRoot
+          ? []
+          : [{ code: "tail-reseal-receipt-root-mismatch" }],
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      receiptRoot: "",
+      failures: [{ code: error.code || "tail-reseal-receipt-invalid" }],
+    };
+  }
+}