@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.10

package/packages/core/providers/github/pipeline-run-entry.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import {
+  PIPELINE_ENTRY,
+  RECOVERY_ENTRY,
+  consumerWorkflows,
+} from "../../consumer/contract/entries.js";
+
+export function pipelineRunEntry(run) {
+  const definitions = (run.referenced_workflows || []).filter((item) =>
+    [PIPELINE_ENTRY, RECOVERY_ENTRY].some((entry) =>
+      item.path?.startsWith(`kungfu-systems/buildchain/${entry}@`),
+    ),
+  );
+  if (
+    definitions.length !== 1 ||
+    !/^[0-9a-f]{40}$/u.test(definitions[0].sha || "")
+  )
+    throw new Error(
+      "Build provider run has no unique exact pipeline or recovery entry",
+    );
+  const definition = definitions[0];
+  const recovery = definition.path.startsWith(
+    `kungfu-systems/buildchain/${RECOVERY_ENTRY}@`,
+  );
+  const caller = `.github/workflows/${recovery ? "buildchain-recover" : "buildchain"}.yml`;
+  const channel = definition.path
+    .split("@")
+    .at(-1)
+    .replace(/^refs\/tags\//u, "");
+  if (
+    !["v4", "v4-alpha"].includes(channel) ||
+    run.path?.split("@")[0] !== caller ||
+    (recovery
+      ? run.event !== "workflow_dispatch"
+      : ![
+          "pull_request",
+          "repository_dispatch",
+          "pull_request_review",
+          "merge_group",
+        ].includes(run.event))
+  )
+    throw new Error(
+      "Build run did not enter through its trusted published consumer workflow",
+    );
+  return { definition, channel, caller, recovery };
+}
+
+// Entry presence and a matching job name alone are insufficient: an altered
+// caller could add a lookalike job beside a failed reusable-workflow call.
+export async function readPipelineCaller(run, configPath, request, repository) {
+  const entry = pipelineRunEntry(run);
+  if (
+    run.repository?.full_name !== repository ||
+    run.head_repository?.full_name !== repository ||
+    !/^[0-9a-f]{40}$/u.test(run.head_sha || "")
+  )
+    throw new Error("Pipeline execution crossed a repository or fork boundary");
+  const file = await request(
+    `/repos/${repository}/contents/${entry.caller}?ref=${run.head_sha}`,
+  );
+  if (
+    file.type !== "file" ||
+    file.encoding !== "base64" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 64000 ||
+    typeof file.content !== "string" ||
+    file.content.length > 128000
+  )
+    throw new Error("Pipeline caller workflow is absent or exceeds its bound");
+  const bytes = Buffer.from(file.content, "base64");
+  const blob = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (
+    bytes.length !== file.size ||
+    blob !== file.sha ||
+    bytes.toString("utf8") !==
+      consumerWorkflows(entry.channel, configPath)[entry.caller]
+  )
+    throw new Error(
+      "Pipeline caller differs from the trusted minimal workflow contract",
+    );
+  return { commit: run.head_sha, path: entry.caller, blob };
+}

package/packages/core/providers/github/pipeline-runs.js

@@ -0,0 +1,132 @@
+import { providerWriter } from "../../workflow/attempt/identity.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelineRunEntry, readPipelineCaller } from "./pipeline-run-entry.js";
+
+function uniqueJob(jobs, name) {
+  const matches = jobs.filter(
+    (job) => job.name === name || job.name.endsWith(` / ${name}`),
+  );
+  if (matches.length !== 1)
+    throw new Error(`Pipeline needs one exact provider job: ${name}`);
+  return matches[0];
+}
+
+export function githubPipelineRuns(request, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline run repository");
+  const base = `/repos/${repository}`;
+  async function read(runId, runAttempt) {
+    for (const value of [runId, runAttempt])
+      if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error("Invalid pipeline run coordinates");
+    const run = await request(`${base}/actions/runs/${runId}`);
+    if (
+      run.id !== runId ||
+      run.run_attempt !== runAttempt ||
+      run.repository?.full_name !== repository
+    )
+      throw new Error("Pipeline provider run attempt changed");
+    const jobs = [];
+    for (let page = 1; page <= 100; page++) {
+      const response = await request(
+        `${base}/actions/runs/${runId}/attempts/${runAttempt}/jobs?per_page=100&page=${page}`,
+      );
+      if (!Array.isArray(response.jobs))
+        throw new Error("Missing pipeline provider jobs");
+      jobs.push(...response.jobs);
+      if (response.jobs.length < 100) return { run, jobs };
+    }
+    throw new Error("Pipeline job inventory exceeds its bound");
+  }
+  async function writer(runId, runAttempt, jobName) {
+    const { jobs } = await read(runId, runAttempt);
+    const job = uniqueJob(jobs, jobName);
+    if (
+      job.run_id !== runId ||
+      job.run_attempt !== runAttempt ||
+      job.status !== "in_progress"
+    )
+      throw new Error("Pipeline writer is not the exact active provider job");
+    const value = {
+      repository,
+      runId: String(runId),
+      runAttempt: String(runAttempt),
+      jobId: String(job.id),
+    };
+    providerWriter(value, repository);
+    return value;
+  }
+  async function build(runId, runAttempt, source, platforms) {
+    const { run, jobs } = await read(runId, runAttempt);
+    if (
+      ![
+        "pull_request",
+        "repository_dispatch",
+        "pull_request_review",
+        "merge_group",
+        "workflow_dispatch",
+      ].includes(run.event) ||
+      (["pull_request", "merge_group"].includes(run.event) &&
+        run.head_sha !== source.commit) ||
+      source.repository !== repository
+    )
+      throw new Error("Build provider run does not match admitted PR source");
+    const entry = pipelineRunEntry(run);
+    await readPipelineCaller(run, source.configPath, request, repository);
+    if (
+      !Array.isArray(platforms) ||
+      !platforms.length ||
+      new Set(platforms).size !== platforms.length
+    )
+      throw new Error(
+        "Build provider receipt requires declared unique platforms",
+      );
+    const selected = platforms.map((platform) =>
+      uniqueJob(jobs, `Build product (${platform})`),
+    );
+    if (
+      selected.some(
+        (job) =>
+          job.run_id !== runId ||
+          job.run_attempt !== runAttempt ||
+          job.status !== "completed" ||
+          !job.conclusion,
+      )
+    )
+      throw new Error("Product build jobs are not provider-terminal");
+    const again = await request(`${base}/actions/runs/${runId}`);
+    if (
+      again.id !== run.id ||
+      again.run_attempt !== runAttempt ||
+      again.head_sha !== run.head_sha
+    )
+      throw new Error("Product build run changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-build-readback/v1",
+      source,
+      runId,
+      runAttempt,
+      entry: entry.definition,
+      jobs: selected,
+      outcome: selected.every((job) => job.conclusion === "success")
+        ? "success"
+        : "failure",
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  async function completed(
+    runId,
+    runAttempt,
+    { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {},
+  ) {
+    for (let attempt = 0; attempt < 20; attempt++) {
+      const { run } = await read(runId, runAttempt);
+      if (run.status === "completed") return run;
+      await sleep(3000);
+    }
+    throw new Error(
+      "Predecessor workflow did not become terminal within the bounded provider readback window",
+    );
+  }
+  return { read, writer, build, completed };
+}

package/packages/core/providers/github/pipeline-source.js

@@ -0,0 +1,195 @@
+import { bindConsumerSource } from "../../consumer/contract/identity.js";
+import { normalInputs } from "../../consumer/contract/entries.js";
+import { channelRoute } from "../../workflow/pipeline/events.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { validateGeneration } from "../../workflow/attempt/identity.js";
+
+function exactSha(value) {
+  if (!/^[0-9a-f]{40}$/u.test(value || ""))
+    throw new Error("Pipeline source requires an exact Git commit");
+  return value;
+}
+
+function sourceRefBinding(reference) {
+  return {
+    ref: reference?.ref ?? null,
+    sha: reference?.sha ?? null,
+    repository: {
+      id: reference?.repo?.id ?? null,
+      nodeId: reference?.repo?.node_id ?? null,
+      fullName: reference?.repo?.full_name ?? null,
+    },
+  };
+}
+
+function mergedCommit(pr) {
+  return pr.merged === true ? pr.merge_commit_sha : null;
+}
+
+function pullRequestBinding(pr) {
+  // Provider timestamps and repository metadata can change during our own
+  // evidence writes. Bind source and delivery state, not those unrelated fields.
+  return {
+    number: pr.number,
+    state: pr.state,
+    merged: pr.merged,
+    mergeCommit: mergedCommit(pr),
+    head: sourceRefBinding(pr.head),
+    base: sourceRefBinding(pr.base),
+    draft: pr.draft,
+    ready: pr.labels.some((label) => label.name === "ready"),
+  };
+}
+
+export function githubPipelineSource(request, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline repository");
+  const base = `/repos/${repository}`;
+  async function source(commitInput, configPath) {
+    const commit = exactSha(commitInput);
+    const git = await request(`${base}/git/commits/${commit}`);
+    const config = await request(
+      `${base}/contents/${configPath}?ref=${commit}`,
+    );
+    if (
+      config.type !== "file" ||
+      config.encoding !== "base64" ||
+      !Number.isSafeInteger(config.size) ||
+      config.size < 1 ||
+      config.size > 256_000 ||
+      typeof config.content !== "string" ||
+      config.content.length > 512_000
+    )
+      throw new Error("Pipeline TOML is missing or exceeds its byte bound");
+    const bytes = Buffer.from(config.content, "base64");
+    if (bytes.length !== config.size)
+      throw new Error("Pipeline TOML size drift");
+    return bindConsumerSource(
+      {
+        repository,
+        commit,
+        tree: exactSha(git.tree?.sha),
+        configPath,
+        configBlob: config.sha,
+      },
+      bytes,
+    );
+  }
+  async function branchHead(branch) {
+    if (
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        branch || "",
+      ) ||
+      branch.includes("..")
+    )
+      throw new Error("Invalid protected branch");
+    const pointer = await request(`${base}/git/ref/heads/${branch}`);
+    if (pointer.object?.type !== "commit")
+      throw new Error("Protected ref is not a commit");
+    return exactSha(pointer.object.sha);
+  }
+  async function observe(pullRequest, inputs = {}) {
+    if (!Number.isSafeInteger(pullRequest) || pullRequest < 1)
+      throw new Error("Pipeline requires an exact PR number");
+    const { configPath } = normalInputs(inputs);
+    const pr = await request(`${base}/pulls/${pullRequest}`);
+    const repositoryInfo = await request(base);
+    if (pr.number !== pullRequest || !repositoryInfo.node_id)
+      throw new Error("Pipeline PR provider identity drift");
+    // Read delivery policy from the protected base. A PR may change its own
+    // product commands, but cannot lower review or grant itself a channel route.
+    const baseCommit = await branchHead(pr.base?.ref);
+    const protectedSource = await source(baseCommit, configPath);
+    const route = channelRoute(protectedSource.plan, pr, repository);
+    if (!route) {
+      if (baseCommit !== (await branchHead(pr.base.ref)))
+        throw new Error("Protected policy changed during route observation");
+      return { eligible: false, reason: "channel-not-enabled" };
+    }
+    const admitted = await source(pr.head.sha, configPath);
+    const again = await request(`${base}/pulls/${pullRequest}`);
+    if (
+      recordDigest(pullRequestBinding(pr)) !==
+        recordDigest(pullRequestBinding(again)) ||
+      baseCommit !== (await branchHead(pr.base.ref))
+    )
+      throw new Error("Pipeline source changed during observation; reobserve");
+    return {
+      eligible: true,
+      repositoryId: repositoryInfo.node_id,
+      route,
+      plan: admitted.plan,
+      protectedPlan: protectedSource.plan,
+      protectedSource: protectedSource.identity,
+      live: {
+        pullRequest,
+        observedHead: pr.head.sha,
+        targetBranch: pr.base.ref,
+        routeEnabled: true,
+        source: admitted.identity,
+        baseCommit,
+        state: pr.state,
+        merged: pr.merged === true,
+        mergeCommit: mergedCommit(pr),
+        draft: pr.draft === true,
+        ready: pr.labels.some((label) => label.name === "ready"),
+      },
+    };
+  }
+  async function observeIntent(intent, generation, inputs = {}) {
+    validateGeneration(generation, intent);
+    if (intent.repository !== repository)
+      throw new Error("Recorded intent repository drift");
+    const number = intent.source.pullRequest;
+    const pr = await request(`${base}/pulls/${number}`);
+    const repositoryInfo = await request(base);
+    if (
+      repositoryInfo.node_id !== intent.source.repositoryId ||
+      pr.number !== number ||
+      pr.base?.repo?.full_name !== repository
+    )
+      throw new Error("Recorded pipeline intent provider identity drift");
+    const sameHead =
+      pr.head?.repo?.full_name === repository &&
+      pr.head.sha === generation.source.commit;
+    const live = {
+      pullRequest: number,
+      observedHead: exactSha(pr.head?.sha),
+      targetBranch: pr.base.ref,
+      state: pr.state,
+      merged: pr.merged === true,
+      mergeCommit: mergedCommit(pr),
+      source: sameHead ? generation.source : null,
+      baseCommit: null,
+      ready: pr.labels.some((label) => label.name === "ready"),
+      draft: pr.draft === true,
+    };
+    // Closing, updating or retargeting an admitted PR must remain recoverable
+    // even when its new TOML is invalid, its old route disappeared or it is now a fork.
+    if (
+      pr.state !== "open" ||
+      !sameHead ||
+      pr.base.ref !== intent.source.targetBranch
+    ) {
+      const again = await request(`${base}/pulls/${number}`);
+      if (
+        recordDigest(pullRequestBinding(pr)) !==
+        recordDigest(pullRequestBinding(again))
+      )
+        throw new Error("Recorded intent changed during terminal observation");
+      return { eligible: true, cleanupOnly: true, live };
+    }
+    const observed = await observe(number, inputs);
+    if (observed.eligible) return observed;
+    return {
+      eligible: true,
+      cleanupOnly: true,
+      live: {
+        ...live,
+        baseCommit: await branchHead(intent.source.targetBranch),
+        routeEnabled: false,
+      },
+    };
+  }
+  return { observe, observeIntent, source, branchHead };
+}

package/packages/core/providers/github/pipeline-stable-baseline.js

@@ -0,0 +1,86 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  SETTLEMENT_ASSET,
+  verifyPublicationSettlement,
+} from "../../publication/settlement/transaction.js";
+import { readReleaseEvidenceAssets } from "./release-evidence-assets.js";
+
+// Earlier publications materialized the floating entry after the exact tag.
+// Only their completed immutable settlement can bind those two commits.
+export async function readPipelineStableBaseline(plan, host, release, prior) {
+  if ((prior?.commit || null) === plan.previousChannelCommit) return null;
+  if (!release || !prior || !plan.previousChannelCommit)
+    throw new Error(
+      "Stable comparison differs from the retained published channel",
+    );
+  const evidence = await readReleaseEvidenceAssets(host, release, [
+    SETTLEMENT_ASSET,
+    "buildchain.release.json",
+  ]);
+  if (evidence.status !== "present")
+    throw new Error(
+      "Stable channel differs without a completed publication settlement",
+    );
+  const read = (name) =>
+    JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(evidence.values[name]),
+    );
+  const settlement = read(SETTLEMENT_ASSET),
+    publicPassport = read("buildchain.release.json"),
+    repository = plan.source.repository,
+    tag = release.tag,
+    sourceSha = prior.commit;
+  if (
+    settlement.schemaVersion !== 1 ||
+    settlement.contract !== "buildchain-v4-publication-settlement/v1" ||
+    settlement.release?.tag !== tag ||
+    settlement.release?.sourceSha !== sourceSha ||
+    settlement.release?.channel !== "stable"
+  )
+    throw new Error(
+      "Stable baseline settlement has different release coordinates",
+    );
+  const verified = verifyPublicationSettlement(settlement.documents, {
+    repository,
+    tag,
+    sourceSha,
+    publicPassport,
+  });
+  const { product, providerState, productState, invocation, passport } =
+    settlement.documents;
+  const ref = `refs/tags/v${plan.version.split(".")[0]}`,
+    updates = product.updates.filter((value) => value.ref === ref);
+  const subject = {
+    repository,
+    sourceSha,
+    tag,
+    version: tag.slice(1),
+    channel: "stable",
+  };
+  if (
+    invocation.target.channel !== "stable" ||
+    passport.release.channel !== "stable" ||
+    product.promotedSha !== plan.previousChannelCommit ||
+    updates.length !== 1 ||
+    updates[0].action !== "converged-release-tag" ||
+    updates[0].sha !== plan.previousChannelCommit ||
+    recordDigest(productState.subject) !== recordDigest(subject) ||
+    recordDigest(providerState.subject) !==
+      recordDigest({
+        ...subject,
+        sourceSha: plan.previousChannelCommit,
+      })
+  )
+    throw new Error(
+      "Stable baseline settlement does not bind the retained floating channel",
+    );
+  return {
+    releaseId: release.id,
+    tag,
+    sourceSha,
+    channelRef: ref,
+    channelCommit: plan.previousChannelCommit,
+    receiptRoot: verified.receiptRoot,
+    assets: evidence.assets,
+  };
+}