@kungfu-tech/buildchain 4.0.2-alpha.4 → 4.0.2-alpha.41

package/scripts/v4-publication-settlement.mjs

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createV4ReleaseInvocation,
+  createV4ReleaseReceipt,
+  createV4ReleaseTransaction,
+} from "../packages/core/v4-release-invocation.js";
+import {
+  releaseTailRoot,
+  validateReleaseTailTransaction,
+} from "../packages/core/release-tail-provider-plane.js";
+
+export const SETTLEMENT_ASSET = "buildchain-publication-settlement.json";
+
+export function verifyPublicationSettlement(
+  documents,
+  { repository, tag, sourceSha, publicPassport, candidateSha } = {},
+) {
+  const {
+    invocation,
+    transaction,
+    receipt,
+    passport,
+    product,
+    providerState,
+    productState,
+  } = documents;
+  const projected = createV4ReleaseInvocation(invocation);
+  const roots = createV4ReleaseTransaction({
+    invocationRoot: projected.roots.invocationRoot,
+    publisherRoot: projected.roots.publisherRoot,
+    runtimeRoot: projected.roots.runtimeRoot,
+    providerRoot: projected.roots.providerRoot,
+    parentRoot: projected.roots.parentRoot,
+  });
+  const { receiptRoot, ...receiptBody } = receipt;
+  const { passportRoot, ...passportBody } = passport;
+  const { root: productRoot, ...productBody } = product;
+  if (
+    !validateReleaseTailTransaction(providerState).valid ||
+    !validateReleaseTailTransaction(productState).valid
+  )
+    throw new Error("invalid provider transaction state");
+  if (
+    releaseTailRoot(transaction) !==
+      releaseTailRoot({
+        ...roots.transaction,
+        transactionRoot: roots.transactionRoot,
+      }) ||
+    createV4ReleaseReceipt(receiptBody).receiptRoot !== receiptRoot ||
+    receipt.transactionRoot !== roots.transactionRoot ||
+    receipt.outcome !== "complete" ||
+    passportRoot !== releaseTailRoot(passportBody) ||
+    receipt.releasePassportRoot !== passportRoot ||
+    productRoot !== releaseTailRoot(productBody) ||
+    !receipt.providerReceiptRoots.includes(productRoot) ||
+    receipt.providerTransactionRoot !== providerState.transactionRoot ||
+    receipt.providerStateRoot !== providerState.stateRoot ||
+    providerState.state !== "complete" ||
+    productState.state !== "complete" ||
+    product.transaction.stateRoot !== productState.stateRoot ||
+    product.transaction.transactionRoot !== productState.transactionRoot ||
+    productState.transactionRoot !== roots.transactionRoot ||
+    providerState.receipts.some(
+      ({ receiptRoot: root }) => !receipt.providerReceiptRoots.includes(root),
+    )
+  )
+    throw new Error("terminal publication receipt lineage does not verify");
+  verifyPublicationCoordinates(documents, {
+    repository,
+    tag,
+    sourceSha,
+    publicPassport,
+    candidateSha,
+  });
+  return { publication: "complete", receiptRoot, sourceSha, tag, repository };
+}
+
+function verifyPublicationCoordinates(
+  { invocation, passport, product },
+  { repository, tag, sourceSha, publicPassport, candidateSha },
+) {
+  if (
+    invocation.candidate.repository !== repository ||
+    (candidateSha && invocation.candidate.commit !== candidateSha) ||
+    passport.repository !== repository ||
+    invocation.provider.repository !== repository ||
+    invocation.target.tag !== tag ||
+    passport.release.tag !== tag ||
+    passport.release.version !== tag.replace(/^v/u, "") ||
+    product.publication.exactTag !== tag ||
+    product.publication.version !== passport.release.version ||
+    product.publication.releaseSha !== sourceSha ||
+    product.publication.state !== "complete" ||
+    product.publication.finalizationNeeded ||
+    passport.source.headSha !== invocation.candidate.commit ||
+    passport.source.treeHash !== invocation.candidate.tree ||
+    passport.policyDigest !== invocation.authority.policyRoot ||
+    passport.publicationQualificationRoot !==
+      invocation.authority.qualificationRoot ||
+    (publicPassport &&
+      releaseTailRoot(publicPassport) !== releaseTailRoot(passport))
+  )
+    throw new Error(
+      "publication evidence does not match exact provider release coordinates",
+    );
+}
+
+export function readApplyDocuments(base) {
+  const read = (relative) =>
+    JSON.parse(fs.readFileSync(path.join(base, relative)));
+  return {
+    invocation: read("release-tail/release-invocation.json"),
+    transaction: read("release-tail/release-transaction.json"),
+    receipt: read("release-tail/release-receipt.json"),
+    product: read("release-tail/product-provider-result.json"),
+    providerState: read("release-tail/state.json"),
+    productState: read("release-tail/product-provider-transaction.json"),
+    passport: read("release-passport/buildchain.release.json"),
+  };
+}
+
+export async function settlePublication({
+  base,
+  client,
+  applyOutcome,
+  repository,
+  candidateSha,
+}) {
+  const documents = readApplyDocuments(base);
+  if (
+    documents.invocation.candidate.repository !== repository ||
+    (candidateSha && documents.invocation.candidate.commit !== candidateSha)
+  )
+    throw new Error(
+      "publication settlement does not match the admitted repository and candidate",
+    );
+  const tag = documents.invocation.target.tag;
+  const release = client.release(tag);
+  const sourceSha = client.json(
+    `repos/${repository}/commits/${encodeURIComponent(tag)}`,
+  ).sha;
+  const matches = release.assets.filter(
+    ({ name }) => name === "buildchain.release.json",
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      "exact public publication passport is missing or ambiguous",
+    );
+  const publicPassport = JSON.parse(client.assetBytes(matches[0]));
+  const status = verifyPublicationSettlement(documents, {
+    repository,
+    tag,
+    sourceSha,
+    publicPassport,
+  });
+  // Publication completion is immutable; next-development and distribution progress stay separate.
+  const settlement = {
+    schemaVersion: 1,
+    contract: "buildchain-v4-publication-settlement/v1",
+    id: "v4-publication",
+    release: { sourceSha, tag, channel: documents.invocation.target.channel },
+    documents,
+  };
+  const file = path.join(base, "release-tail", SETTLEMENT_ASSET);
+  client.write(file, settlement);
+  await client.publish(release, [file]);
+  const summary = {
+    ...status,
+    nextDevelopment: applyOutcome === "success" ? "advanced" : "incomplete",
+    binaryDistribution: "pending-provider-readback",
+  };
+  client.write(
+    path.join(base, "release-tail", "delivery-summary.json"),
+    summary,
+  );
+  return { summary, receipt: documents.receipt };
+}
+
+async function main() {
+  const { releaseAssetClient } = await import("./release-asset-client.mjs");
+  const repository = process.env.GITHUB_REPOSITORY;
+  const result = await settlePublication({
+    base: process.argv[2],
+    client: releaseAssetClient(repository),
+    repository,
+    candidateSha: process.env.CANDIDATE_SHA,
+    applyOutcome: process.env.APPLY_OUTCOME,
+  });
+  if (process.env.GITHUB_OUTPUT)
+    fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `receipt-json=${JSON.stringify(result.receipt)}\nreceipt-root=${result.receipt.receiptRoot}\nstatus=complete\n`,
+    );
+  if (process.env.GITHUB_STEP_SUMMARY)
+    fs.appendFileSync(
+      process.env.GITHUB_STEP_SUMMARY,
+      `Publication: **complete**, receipt \`${result.receipt.receiptRoot}\`. Next development: **${result.summary.nextDevelopment}**. Binary distribution: **pending provider readback**.\n`,
+    );
+}
+
+if (
+  process.argv[1] &&
+  path.basename(process.argv[1]) === "v4-publication-settlement.mjs" &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+)
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/scripts/v4-universal-workflow-backflow.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  validateV4UniversalWorkflowRequest,
+  v4UniversalWorkflowRequestRoot,
+} from "../packages/core/v4-universal-workflow-bootstrap.js";
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))
+        .map((key) => [key, canonical(value[key])]),
+    );
+  return value;
+}
+
+function contentRoot(domain, value) {
+  const hash = crypto.createHash("sha256");
+  hash.update(domain, "utf8");
+  hash.update(Buffer.from([0]));
+  hash.update(`${JSON.stringify(canonical(value))}\n`, "utf8");
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function validateTerminalReceipt(value, request) {
+  if (
+    value?.schema !==
+      "kungfu-buildchain-v4-universal-workflow-terminal-receipt/v1" ||
+    value.status !== "succeeded" ||
+    value.runtime?.repository !== request.candidate.repository ||
+    value.runtime?.sha !== request.candidate.expectedSha ||
+    value.requestRoot !== v4UniversalWorkflowRequestRoot(request) ||
+    !SHA.test(value.runtime?.sha || "") ||
+    !ROOT.test(value.receiptRoot || "")
+  )
+    fail(
+      "successful exact-candidate terminal receipt is required for backflow",
+    );
+  return value;
+}
+
+export function createV4UniversalBackflowPlan({
+  request: requestValue,
+  receipt,
+}) {
+  const request = validateV4UniversalWorkflowRequest(requestValue);
+  if (request.mode !== "train") fail("only Train delivery can create backflow");
+  if (request.capability.id !== "release-candidate-promote")
+    fail("only a release-candidate-promote delivery can create backflow");
+  if (request.payload?.inputs?.["dry-run"] !== false)
+    fail("only a non-dry-run release delivery can create backflow");
+  const terminal = validateTerminalReceipt(receipt, request);
+  const marker = `<!-- buildchain-universal-backflow:${request.candidate.expectedSha} -->`;
+  const binding = {
+    schema: "kungfu-buildchain-v4-universal-workflow-backflow/v1",
+    repository: request.candidate.repository,
+    pullRequest: request.candidate.reviewPullRequest,
+    baseRef: "dev/v4/v4.0",
+    trainSha: request.candidate.expectedSha,
+    consumerRepository: request.consumer.repository,
+    consumerSha: request.consumer.sourceSha,
+    requestRoot: terminal.requestRoot,
+    terminalReceiptRoot: terminal.receiptRoot,
+  };
+  const backflowRoot = contentRoot("universal-workflow-backflow", binding);
+  return {
+    ...binding,
+    marker,
+    backflowRoot,
+    body: [
+      marker,
+      "## Universal Train backflow",
+      "",
+      `- Train SHA: \`${binding.trainSha}\``,
+      `- Consumer: \`${binding.consumerRepository}@${binding.consumerSha}\``,
+      `- Request root: \`${binding.requestRoot}\``,
+      `- Terminal receipt root: \`${binding.terminalReceiptRoot}\``,
+      `- Backflow root: \`${backflowRoot}\``,
+      "",
+      "This receipt binds a successful consumer delivery to the protected Train-to-dev backflow PR; it does not designate the Train candidate as a Buildchain release.",
+    ].join("\n"),
+  };
+}
+
+function githubHeaders(token) {
+  return {
+    accept: "application/vnd.github+json",
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    "user-agent": "buildchain-universal-backflow",
+    "x-github-api-version": "2022-11-28",
+  };
+}
+
+async function githubJson({ path, method = "GET", token, body, fetchImpl }) {
+  const api = String(
+    process.env.GITHUB_API_URL || "https://api.github.com",
+  ).replace(/\/+$/u, "");
+  const response = await fetchImpl(`${api}${path}`, {
+    method,
+    headers: githubHeaders(token),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  const value = text ? JSON.parse(text) : {};
+  if (!response.ok)
+    fail(
+      `GitHub API ${method} ${path} failed with ${response.status}: ${value.message || text}`,
+    );
+  return value;
+}
+
+export async function upsertV4UniversalBackflow({
+  request,
+  receipt,
+  token,
+  fetchImpl = globalThis.fetch,
+}) {
+  const admitted = validateV4UniversalWorkflowRequest(request);
+  if (
+    admitted.mode !== "train" ||
+    admitted.capability.id !== "release-candidate-promote" ||
+    admitted.payload?.inputs?.["dry-run"] !== false
+  ) {
+    return {
+      schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
+      action: "skipped",
+      reason: "not-a-successful-non-dry-run-release-delivery",
+      backflowRoot: "",
+    };
+  }
+  if (!token) fail("GH_TOKEN is required for protected backflow");
+  if (typeof fetchImpl !== "function") fail("fetch is required for backflow");
+  const plan = createV4UniversalBackflowPlan({ request: admitted, receipt });
+  const encodedRepository = plan.repository;
+  const pull = await githubJson({
+    path: `/repos/${encodedRepository}/pulls/${plan.pullRequest}`,
+    token,
+    fetchImpl,
+  });
+  if (
+    pull.state !== "open" ||
+    pull.base?.ref !== plan.baseRef ||
+    pull.head?.repo?.full_name !== plan.repository ||
+    pull.head?.sha !== plan.trainSha
+  )
+    fail("backflow PR no longer binds the exact admitted Train candidate");
+  const comments = await githubJson({
+    path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments?per_page=100`,
+    token,
+    fetchImpl,
+  });
+  const existing = comments.find((comment) =>
+    String(comment.body || "").includes(plan.marker),
+  );
+  const comment = existing
+    ? await githubJson({
+        path: `/repos/${encodedRepository}/issues/comments/${existing.id}`,
+        method: "PATCH",
+        token,
+        body: { body: plan.body },
+        fetchImpl,
+      })
+    : await githubJson({
+        path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments`,
+        method: "POST",
+        token,
+        body: { body: plan.body },
+        fetchImpl,
+      });
+  return {
+    schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
+    action: existing ? "updated" : "created",
+    pullRequest: plan.pullRequest,
+    trainSha: plan.trainSha,
+    terminalReceiptRoot: plan.terminalReceiptRoot,
+    backflowRoot: plan.backflowRoot,
+    commentUrl: comment.html_url,
+  };
+}
+
+async function main() {
+  const request = JSON.parse(
+    process.env.BUILDCHAIN_UNIVERSAL_REQUEST_JSON ||
+      fail("request is required"),
+  );
+  const receipt = JSON.parse(
+    process.env.BUILDCHAIN_UNIVERSAL_TERMINAL_RECEIPT_JSON ||
+      fail("terminal receipt is required"),
+  );
+  const result = await upsertV4UniversalBackflow({
+    request,
+    receipt,
+    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+const isMain =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) await main();