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

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

@@ -0,0 +1,240 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+const QUERY = `query PipelinePolicy($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id number headRefOid baseRefName isDraft reviewDecision author{login}}}}`;
+const BRANCH_QUERY = `query PipelineBranchPolicy($owner:String!,$name:String!,$branch:String!,$ref:String!){repository(owner:$owner,name:$name){ref(qualifiedName:$ref){refUpdateRule{requiredApprovingReviewCount requiresCodeOwnerReviews requiredStatusCheckContexts}}mergeQueue(branch:$branch){id}}}`;
+
+async function classicPolicy(request, owner, name, branch) {
+  // Read viewer-enforced rules and the ordinary Contents:read branch projection.
+  // Administrative branchProtectionRule and /protection queries are not needed.
+  const result = await request("/graphql", {
+    method: "POST",
+    body: {
+      query: BRANCH_QUERY,
+      variables: { owner, name, branch, ref: `refs/heads/${branch}` },
+    },
+  });
+  const repository = result.data?.repository;
+  if (!repository?.ref)
+    throw new Error("Protected branch metadata is unavailable");
+  const rule = repository.ref.refUpdateRule;
+  const observed = await request(
+    `/repos/${owner}/${name}/branches/${encodeURIComponent(branch)}`,
+  );
+  const status = observed.protection?.required_status_checks;
+  const contexts = status?.contexts;
+  const checks = status?.checks;
+  if (
+    observed.name !== branch ||
+    !Array.isArray(contexts) ||
+    !Array.isArray(checks) ||
+    checks.some(
+      (check) =>
+        typeof check.context !== "string" ||
+        !check.context ||
+        !Object.hasOwn(check, "app_id") ||
+        !(
+          check.app_id === null ||
+          check.app_id === -1 ||
+          (Number.isSafeInteger(check.app_id) && check.app_id > 0)
+        ),
+    ) ||
+    contexts.some(
+      (context) => !checks.some((check) => check.context === context),
+    ) ||
+    checks.some((check) => !contexts.includes(check.context)) ||
+    (rule?.requiredStatusCheckContexts || []).some(
+      (context) => !contexts.includes(context),
+    )
+  )
+    throw new Error("Protected branch check identity metadata is incomplete");
+  return {
+    required_merge_queue: Boolean(repository.mergeQueue?.id),
+    required_pull_request_reviews:
+      rule?.requiredApprovingReviewCount > 0
+        ? {
+            require_code_owner_reviews: rule.requiresCodeOwnerReviews,
+            required_approving_review_count: rule.requiredApprovingReviewCount,
+          }
+        : null,
+    required_status_checks: {
+      checks,
+    },
+  };
+}
+
+async function inventory(request, url, key = "") {
+  const rows = [];
+  for (let page = 1; page <= 100; page++) {
+    const response = await request(
+      `${url}${url.includes("?") ? "&" : "?"}per_page=100&page=${page}`,
+    );
+    const entries = key ? response[key] : response;
+    if (!Array.isArray(entries))
+      throw new Error("Missing protected policy inventory");
+    rows.push(...entries);
+    if (entries.length < 100) return rows;
+  }
+  throw new Error("Protected policy inventory exceeds its bound");
+}
+
+function protections(rules, classic, policy) {
+  const reviews = rules
+    .filter((rule) => rule.type === "pull_request")
+    .map((rule) => rule.parameters);
+  if (classic?.required_pull_request_reviews)
+    reviews.push({
+      ...classic.required_pull_request_reviews,
+      require_code_owner_review:
+        classic.required_pull_request_reviews.require_code_owner_reviews,
+    });
+  if (
+    !reviews.some((rule) => rule?.require_code_owner_review === true) ||
+    !reviews.some(
+      (rule) =>
+        rule?.required_approving_review_count >= policy.minimum_approvals,
+    ) ||
+    !(
+      classic?.required_merge_queue ||
+      rules.some((rule) => rule.type === "merge_queue")
+    )
+  )
+    throw new Error(
+      "Protected branch must enforce declared approvals, code owners and merge queue",
+    );
+  const contexts = rules
+    .filter((rule) => rule.type === "required_status_checks")
+    .flatMap((rule) => rule.parameters?.required_status_checks || []);
+  for (const check of classic?.required_status_checks?.checks || [])
+    contexts.push({ context: check.context, integration_id: check.app_id });
+  if (!contexts.length || contexts.some((check) => !check.context))
+    throw new Error(
+      "Protected pipeline requires provider-enforced status checks",
+    );
+  return contexts;
+}
+
+function approved(pr, reviews, minimum) {
+  const latest = new Map();
+  for (const review of [...reviews].sort((a, b) => a.id - b.id)) {
+    if (
+      review.user?.login &&
+      ["APPROVED", "CHANGES_REQUESTED", "DISMISSED"].includes(review.state)
+    )
+      latest.set(review.user.login, review);
+  }
+  const independent = [...latest.values()].filter(
+    (review) => review.user.login !== pr.author?.login,
+  );
+  return (
+    pr.reviewDecision === "APPROVED" &&
+    !independent.some((review) => review.state === "CHANGES_REQUESTED") &&
+    independent.filter(
+      (review) =>
+        review.state === "APPROVED" && review.commit_id === pr.headRefOid,
+    ).length >= minimum
+  );
+}
+
+function checksPass(contexts, checks, statuses) {
+  return contexts.every(({ context, integration_id: app }) => {
+    const candidates = checks.filter(
+      (check) =>
+        check.name === context && (!app || app === -1 || check.app?.id === app),
+    );
+    const latest = candidates.sort((a, b) => b.id - a.id)[0];
+    if (latest)
+      return (
+        latest.status === "completed" &&
+        ["success", "neutral", "skipped"].includes(latest.conclusion)
+      );
+    if (app && app !== -1) return false;
+    return (
+      statuses
+        .filter((status) => status.context === context)
+        .sort((a, b) => b.id - a.id)[0]?.state === "success"
+    );
+  });
+}
+
+export function githubPipelinePolicy(request, repository) {
+  const [owner, name] = repository.split("/");
+  const base = `/repos/${repository}`;
+  async function pull(number) {
+    const response = await request("/graphql", {
+      method: "POST",
+      body: { query: QUERY, variables: { owner, name, number } },
+    });
+    const pr = response.data?.repository?.pullRequest;
+    if (!pr?.id || pr.number !== number)
+      throw new Error("Protected PR policy identity is unavailable");
+    return pr;
+  }
+  async function observe(current, policy, integratedHead) {
+    const { source, baseCommit } = current.generation;
+    const number = current.intent.source.pullRequest,
+      branch = current.intent.source.targetBranch;
+    const pr = await pull(number);
+    if (pr.headRefOid !== source.commit || pr.baseRefName !== branch)
+      throw new Error("Protected PR policy source drift");
+    const branchPath = encodeURIComponent(branch);
+    const rules = await inventory(
+      request,
+      `${base}/rules/branches/${branchPath}`,
+    );
+    const classic = await classicPolicy(request, owner, name, branch);
+    const contexts = protections(rules, classic, policy);
+    const reviews = await inventory(request, `${base}/pulls/${number}/reviews`);
+    const checks = await inventory(
+      request,
+      `${base}/commits/${source.commit}/check-runs?filter=latest`,
+      "check_runs",
+    );
+    const statuses = await inventory(
+      request,
+      `${base}/commits/${source.commit}/statuses`,
+    );
+    const again = await pull(number);
+    const ref = await request(`${base}/git/ref/heads/${branch}`);
+    if (
+      recordDigest(pr) !== recordDigest(again) ||
+      ref.object?.sha !== (integratedHead || baseCommit)
+    )
+      throw new Error("Protected policy changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-policy-readback/v1",
+      source,
+      baseCommit,
+      pr,
+      rules,
+      classic: classic || null,
+      reviews,
+      checks,
+      statuses,
+      contexts,
+      review: !pr.isDraft && approved(pr, reviews, policy.minimum_approvals),
+      checksPassing: checksPass(contexts, checks, statuses),
+      ...(integratedHead ? { integratedHead } : {}),
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  async function observeMerged(current, policy, integration) {
+    const { root, ...body } = integration;
+    if (
+      root !== recordDigest(body) ||
+      body.schema !== "buildchain.pipeline-integration-readback/v1" ||
+      body.repository !== repository ||
+      body.sourceHead !== current.generation.source.commit ||
+      body.branch !== current.intent.source.targetBranch ||
+      body.pullRequest !== current.intent.source.pullRequest ||
+      !/^[0-9a-f]{40}$/u.test(body.protectedHead || "")
+    )
+      throw new Error(
+        "Merged review qualification requires exact protected integration evidence",
+      );
+    return observe(current, policy, body.protectedHead);
+  }
+  return {
+    observe: (current, policy) => observe(current, policy),
+    observeMerged,
+  };
+}

package/packages/core/providers/github/pipeline-product-payload.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { canonicalJson } from "../../release/discussion/envelope.js";
+import {
+  publicationFile,
+  publicationPath,
+} from "../../publication/pipeline/files.js";
+const sha256 = (bytes) =>
+  `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+export function pipelineProductPayload({
+  qualified,
+  documents,
+  directory,
+  evidence,
+}) {
+  const payload = (effect) => {
+    if (effect.product.startsWith("evidence:")) {
+      const asset = evidence.find(
+        (entry) => `evidence:${entry.id}` === effect.product,
+      );
+      if (
+        !asset ||
+        sha256(asset.bytes) !== effect.digest ||
+        asset.bytes.length !== effect.size
+      )
+        throw new Error(
+          "Release evidence differs from admitted immutable bytes",
+        );
+      return asset.bytes;
+    }
+    if (effect.product === "release-passport")
+      return Buffer.from(`${canonicalJson(documents.passport)}\n`);
+    const artifact = qualified.artifacts.find(
+      (entry) => entry.id === effect.product,
+    );
+    if (
+      !artifact ||
+      artifact.digest !== effect.digest ||
+      artifact.size !== effect.size
+    )
+      throw new Error(
+        "GitHub Release payload does not match qualified product",
+      );
+    const file = publicationFile(publicationPath(directory, artifact.file));
+    if (file.digest !== artifact.digest || file.size !== artifact.size)
+      throw new Error("GitHub Release payload bytes changed");
+    return file.bytes;
+  };
+  return payload;
+}

package/packages/core/providers/github/pipeline-product-release.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+import { pipelineProductPayload } from "./pipeline-product-payload.js";
+
+const sha256 = (bytes) =>
+  `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+export function githubPipelineProductRelease({
+  github,
+  request,
+  repository,
+  plan,
+  qualified,
+  documents,
+  directory,
+  evidence = [],
+}) {
+  const [owner, repo] = repository.split("/");
+  const prefix = `/repos/${repository}`;
+  const marker = `Buildchain release transaction ${documents.transaction.transactionRoot}`;
+  const payload = pipelineProductPayload({
+    qualified,
+    documents,
+    directory,
+    evidence,
+  });
+  async function tag() {
+    const value = await request(
+      `${prefix}/git/ref/tags/${encodeURIComponent(plan.tag)}`,
+      { allow404: true },
+    );
+    if (!value) return { state: "absent" };
+    let object = value.object;
+    for (let depth = 0; object.type === "tag" && depth < 4; depth++)
+      object = (await request(`${prefix}/git/tags/${object.sha}`)).object;
+    if (object.type !== "commit")
+      throw new Error("Exact release tag does not resolve to a commit");
+    return {
+      state: "present",
+      commit: object.sha,
+      ref: value.ref,
+      objectSha: value.object.sha,
+    };
+  }
+  async function release(create = false) {
+    const observedTag = await tag();
+    if (observedTag.state === "absent" && !create) return null;
+    if (observedTag.commit !== qualified.source.commit)
+      throw new Error("Release requires the exact immutable publication tag");
+    let value = await findRelease();
+    if (!value && create) {
+      let failure;
+      try {
+        await github.rest.repos.createRelease({
+          owner,
+          repo,
+          tag_name: plan.tag,
+          target_commitish: qualified.source.commit,
+          name: plan.tag,
+          body: marker,
+          draft: true,
+          prerelease: plan.channel === "alpha",
+          make_latest: "false",
+        });
+      } catch (error) {
+        failure = error;
+      }
+      for (let attempt = 0; attempt < 3; attempt++) {
+        if (attempt) await setTimeout(1000);
+        value = await findRelease();
+        if (value) break;
+      }
+      if (!value)
+        throw (
+          failure || new Error("Release creation lacks exact provider readback")
+        );
+    }
+    if (
+      value &&
+      (value.tag_name !== plan.tag ||
+        value.body !== marker ||
+        value.prerelease !== (plan.channel === "alpha"))
+    )
+      throw new Error(
+        "Existing GitHub Release belongs to a different immutable transaction",
+      );
+    return value;
+  }
+  const findRelease = () => findPipelineRelease(github, owner, repo, plan.tag);
+  async function asset(effect) {
+    const published = await release();
+    if (!published) return { state: "absent" };
+    const assets = await github.paginate(github.rest.repos.listReleaseAssets, {
+      owner,
+      repo,
+      release_id: published.id,
+      per_page: 100,
+    });
+    const matches = assets.filter((entry) => entry.name === effect.name);
+    if (!matches.length) return { state: "absent" };
+    if (matches.length !== 1 || matches[0].size > 256 * 1024 * 1024)
+      throw new Error(
+        "Release asset identity is ambiguous or exceeds its bound",
+      );
+    const bytes = Buffer.from(
+      (
+        await github.rest.repos.getReleaseAsset({
+          owner,
+          repo,
+          asset_id: matches[0].id,
+          headers: { accept: "application/octet-stream" },
+        })
+      ).data,
+    );
+    return {
+      state: "present",
+      id: matches[0].id,
+      releaseId: published.id,
+      size: bytes.length,
+      digest: sha256(bytes),
+    };
+  }
+  return {
+    async observe(effect) {
+      if (effect.kind === "exact-tag") return tag();
+      if (effect.kind === "release-asset") return asset(effect);
+      if (effect.kind === "release-visibility") {
+        const value = await release();
+        return value && !value.draft
+          ? {
+              state: "present",
+              id: value.id,
+              tag: value.tag_name,
+              prerelease: value.prerelease,
+            }
+          : { state: "absent" };
+      }
+      throw new Error("Unsupported GitHub product publication operation");
+    },
+    matches(effect, observed) {
+      if (observed.state !== "present") return false;
+      if (effect.kind === "exact-tag") return observed.commit === effect.commit;
+      if (effect.kind === "release-asset") {
+        const bytes = payload(effect);
+        return (
+          observed.digest === sha256(bytes) && observed.size === bytes.length
+        );
+      }
+      return (
+        effect.kind === "release-visibility" &&
+        observed.tag === effect.tag &&
+        observed.prerelease === effect.prerelease
+      );
+    },
+    async apply(effect) {
+      if (effect.kind === "exact-tag")
+        return request(`${prefix}/git/refs`, {
+          method: "POST",
+          body: { ref: `refs/tags/${effect.tag}`, sha: effect.commit },
+        });
+      const value = await release(true);
+      if (effect.kind === "release-asset")
+        return github.rest.repos.uploadReleaseAsset({
+          owner,
+          repo,
+          release_id: value.id,
+          name: effect.name,
+          data: payload(effect),
+          headers: { "content-type": "application/octet-stream" },
+        });
+      if (effect.kind === "release-visibility")
+        return github.rest.repos.updateRelease({
+          owner,
+          repo,
+          release_id: value.id,
+          draft: false,
+          make_latest: "false",
+        });
+      throw new Error("Unsupported GitHub product publication operation");
+    },
+  };
+}
+
+async function findPipelineRelease(github, owner, repo, tag) {
+  let pages = 0;
+  const values = await github.paginate(
+    github.rest.repos.listReleases,
+    { owner, repo, per_page: 100 },
+    (response) => {
+      if (++pages > 100)
+        throw new Error("Release inventory exceeds its bounded readback");
+      return response.data.filter((entry) => entry.tag_name === tag);
+    },
+  );
+  if (values.length > 1)
+    throw new Error("Exact release tag has multiple provider releases");
+  return values[0];
+}

package/packages/core/providers/github/pipeline-publication-artifacts.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import artifact from "@actions/artifact";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineCaller } from "./pipeline-run-entry.js";
+import { publicationPath } from "../../publication/pipeline/files.js";
+
+export const pipelinePublicationArtifactName = (plan, platform) =>
+  `buildchain-products-${plan.root.slice(7)}-${platform}`;
+
+export function githubPipelinePublicationArtifacts({
+  request,
+  runs,
+  repository,
+  token,
+  client = artifact,
+}) {
+  const prefix = `/repos/${repository}/actions`;
+  async function upload(plan, manifest, directory) {
+    const paths = [
+      publicationPath(directory, "manifest.json"),
+      ...manifest.artifacts.map(({ file }) => publicationPath(directory, file)),
+    ];
+    const result = await client.uploadArtifact(
+      pipelinePublicationArtifactName(plan, manifest.platform),
+      paths,
+      directory,
+      { retentionDays: 30, compressionLevel: 0 },
+    );
+    if (!result.id || !result.digest)
+      throw new Error(
+        "Product upload omitted its immutable provider coordinates",
+      );
+    return result;
+  }
+  async function buildReadback(context, selectedPlatforms) {
+    const { plan, materialization, runId, runAttempt } = context;
+    const { run, jobs } = await runs.read(runId, runAttempt);
+    await readPipelineCaller(
+      run,
+      materialization.source.configPath,
+      request,
+      repository,
+    );
+    const declared = [
+      ...new Set(plan.outputs.map(({ platform }) => platform)),
+    ].sort();
+    const platforms = selectedPlatforms || declared;
+    if (
+      !platforms.length ||
+      new Set(platforms).size !== platforms.length ||
+      platforms.some((platform) => !declared.includes(platform))
+    )
+      throw new Error("Publication subset must name unique declared platforms");
+    const selected = platforms.map((platform) => {
+      const name = `Build publication (${platform})`;
+      const matches = jobs.filter(
+        (job) => job.name === name || job.name.endsWith(` / ${name}`),
+      );
+      if (
+        matches.length !== 1 ||
+        matches[0].run_id !== runId ||
+        matches[0].run_attempt !== runAttempt ||
+        matches[0].status !== "completed" ||
+        matches[0].conclusion !== "success"
+      )
+        throw new Error(
+          "Publication needs every exact credentialless build job to succeed",
+        );
+      return matches[0];
+    });
+    const response = await request(
+      `${prefix}/runs/${runId}/artifacts?per_page=100`,
+    );
+    if (
+      !Array.isArray(response.artifacts) ||
+      response.total_count !== response.artifacts.length ||
+      response.total_count > 100
+    )
+      throw new Error("Publication artifact inventory is incomplete");
+    const assets = platforms.map((platform) => {
+      const matches = response.artifacts.filter(
+        (asset) =>
+          asset.name === pipelinePublicationArtifactName(plan, platform),
+      );
+      if (
+        matches.length !== 1 ||
+        !Number.isSafeInteger(matches[0].id) ||
+        matches[0].id < 1 ||
+        matches[0].expired ||
+        matches[0].workflow_run?.id !== runId ||
+        matches[0].workflow_run?.head_sha !== run.head_sha ||
+        !/^sha256:[0-9a-f]{64}$/u.test(matches[0].digest || "")
+      )
+        throw new Error(
+          "Publication requires one retained artifact per exact platform",
+        );
+      return matches[0];
+    });
+    const again = await runs.read(runId, runAttempt);
+    for (const job of selected)
+      if (
+        !again.jobs.some((entry) => recordDigest(entry) === recordDigest(job))
+      )
+        throw new Error(
+          "Publication build changed during independent readback",
+        );
+    if (again.run.head_sha !== run.head_sha)
+      throw new Error("Publication provider source changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-publication-build-readback/v1",
+      outcome: "success",
+      planRoot: plan.root,
+      source: materialization.source,
+      runId,
+      runAttempt,
+      providerSource: run.head_sha,
+      platforms,
+      jobs: selected,
+      artifactIds: assets.map(({ id }) => id).sort((a, b) => a - b),
+    };
+    return { build: { ...body, root: recordDigest(body) }, assets };
+  }
+  async function download(context, workspace, selectedPlatforms) {
+    const { build, assets } = await buildReadback(context, selectedPlatforms);
+    const [repositoryOwner, repositoryName] = repository.split("/");
+    const bundles = [];
+    for (const asset of assets) {
+      const directory = path.join(workspace, String(asset.id));
+      fs.mkdirSync(directory, { recursive: true });
+      const result = await client.downloadArtifact(asset.id, {
+        path: directory,
+        expectedHash: asset.digest,
+        findBy: {
+          repositoryOwner,
+          repositoryName,
+          workflowRunId: context.runId,
+          token,
+        },
+      });
+      if (result.digestMismatch)
+        throw new Error(
+          "Product download digest does not match the provider archive",
+        );
+      const manifest = JSON.parse(
+        fs.readFileSync(publicationPath(directory, "manifest.json"), "utf8"),
+      );
+      bundles.push({ directory, manifest, providerArtifact: asset });
+    }
+    return { build, bundles };
+  }
+  return { upload, download, buildReadback };
+}

package/packages/core/providers/github/pipeline-release-evidence.js

@@ -0,0 +1,30 @@
+import { readReleaseEvidenceAssets } from "./release-evidence-assets.js";
+
+const NAMES = [
+  "plan",
+  "qualification",
+  "capsules",
+  "invocation",
+  "attestation",
+  "release",
+];
+export async function readPipelineReleaseEvidence(host, candidate) {
+  const result = await readReleaseEvidenceAssets(
+    host,
+    candidate,
+    NAMES.map((id) => `buildchain.${id}.json`),
+  );
+  if (result.status !== "present") return result;
+  const values = {};
+  for (const id of NAMES.filter((name) => name !== "attestation"))
+    values[id] = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        result.values[`buildchain.${id}.json`],
+      ),
+    );
+  return {
+    ...result,
+    values,
+    bundle: result.values["buildchain.attestation.json"],
+  };
+}