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

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

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { githubAuthEnv } from "../source-checkout/auth.js";
+import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
+
+// Read-only Git object access for credentialed source qualification. This is a
+// bare repository: no consumer checkout, hooks or build scripts are executed.
+export async function withPipelineSourceObjects(
+  { repository, sourceHead, baseCommit, token },
+  operation,
+) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(repository || "") ||
+    ![sourceHead, baseCommit].every((sha) => /^[0-9a-f]{40}$/u.test(sha || ""))
+  )
+    throw new Error(
+      "Pipeline qualification requires exact repository source coordinates",
+    );
+  const directory = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-pipeline-source-"),
+  );
+  const environment = {
+    ...createNativeChildEnvironment(process.env),
+    GIT_TERMINAL_PROMPT: "0",
+    ...githubAuthEnv(token),
+  };
+  const git = (args) =>
+    execFileSync("git", ["-C", directory, ...args], {
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  try {
+    git(["init", "--bare", "--quiet"]);
+    git([
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      `https://github.com/${repository}.git`,
+      sourceHead,
+      baseCommit,
+    ]);
+    return await operation(directory);
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+import { runtimeSelector } from "../../runtime/entry/selection.js";
+import { pipelineRunEntry, readPipelineCaller } from "./pipeline-run-entry.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export async function pipelineEntryRuns(host, publishedAt) {
+  const created = encodeURIComponent(
+    `>=${new Date(publishedAt).toISOString()}`,
+  );
+  const prefix = `/repos/${host.repository}/actions/workflows/buildchain.yml/runs`;
+  const runs = [],
+    ids = new Set();
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?event=pull_request&status=completed&created=${created}&per_page=100&page=${page}`,
+      { allow404: true },
+    );
+    if (!result && page === 1) return [];
+    if (
+      !Array.isArray(result?.workflow_runs) ||
+      result.workflow_runs.length > 100
+    )
+      throw new Error("Published entry run inventory is incomplete");
+    for (const run of result.workflow_runs) {
+      if (
+        !Number.isSafeInteger(run.id) ||
+        run.id < 1 ||
+        ids.has(run.id) ||
+        !Number.isSafeInteger(run.run_attempt) ||
+        run.run_attempt < 1 ||
+        !Number.isFinite(Date.parse(run.created_at))
+      )
+        throw new Error(
+          "Published entry run inventory has ambiguous coordinates",
+        );
+      ids.add(run.id);
+      runs.push(run);
+    }
+    if (result.workflow_runs.length < 100)
+      return runs.sort(
+        (a, b) =>
+          Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id,
+      );
+  }
+  throw new Error(
+    "Published entry run inventory exceeds its complete-read bound",
+  );
+}
+
+async function sourceLock(host, source, channel) {
+  const pathname =
+    channel === "v4-alpha"
+      ? ".buildchain/alpha-contract-lock.json"
+      : ".buildchain/contract-lock.json";
+  const file = await host.request(
+    `/repos/${host.repository}/contents/${pathname}?ref=${source.commit}`,
+    { allow404: true },
+  );
+  if (!file) return { value: undefined, evidence: null };
+  if (
+    file.type !== "file" ||
+    file.encoding !== "base64" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 1024 * 1024 ||
+    typeof file.content !== "string" ||
+    file.content.length > 2 * 1024 * 1024
+  )
+    throw new Error("Published entry runtime lock exceeds its source boundary");
+  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)
+    throw new Error("Published entry runtime lock bytes changed");
+  const value = JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  );
+  if (
+    value.schema === "buildchain.consumer-contract-lock/v2" &&
+    value.configDigest !== source.configDigest
+  )
+    throw new Error(
+      "Published entry runtime lock belongs to another consumer configuration",
+    );
+  return {
+    value,
+    evidence: {
+      path: pathname,
+      blob,
+      digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    },
+  };
+}
+
+export async function pipelineEntryRun(run, plan, source, host) {
+  if (
+    run.event !== "pull_request" ||
+    run.status !== "completed" ||
+    run.repository?.full_name !== host.repository ||
+    run.head_repository?.full_name !== host.repository ||
+    run.path?.split("@")[0] !== ".github/workflows/buildchain.yml" ||
+    !Number.isFinite(Date.parse(run.created_at)) ||
+    Date.parse(run.created_at) < Date.parse(source.candidate.publishedAt)
+  )
+    return null;
+  const entry = pipelineRunEntry(run);
+  if (entry.recovery || entry.definition.sha !== source.candidate.sha)
+    return null;
+  const consumer = await host.source.source(
+    run.head_sha,
+    plan.source.configPath,
+  );
+  if (recordDigest(consumer.plan) !== plan.contractRoot) return null;
+  if (
+    consumer.identity.commit !== run.head_sha ||
+    consumer.identity.configPath !== plan.source.configPath ||
+    consumer.identity.repository !== host.repository
+  )
+    throw new Error("Published entry consumer source changed during readback");
+  await readPipelineCaller(
+    run,
+    consumer.identity.configPath,
+    host.request,
+    host.repository,
+  );
+  const lock = await sourceLock(host, consumer.identity, entry.channel);
+  const selection = runtimeSelector({
+    lock: lock.value,
+    workflowSha: entry.definition.sha,
+  });
+  if (selection.ref !== source.candidate.sha) return null;
+  return {
+    source: consumer.identity,
+    entry: entry.definition,
+    selection,
+    lock: lock.evidence,
+  };
+}
+
+export async function pipelineEntryCheck(run, host) {
+  const checks = [],
+    ids = new Set();
+  const prefix = `/repos/${host.repository}/commits/${run.head_sha}/check-runs`;
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?check_name=check&filter=all&per_page=100&page=${page}`,
+    );
+    if (!Array.isArray(result?.check_runs) || result.check_runs.length > 100)
+      throw new Error("Published entry check inventory is incomplete");
+    for (const check of result.check_runs) {
+      if (!Number.isSafeInteger(check.id) || check.id < 1 || ids.has(check.id))
+        throw new Error(
+          "Published entry check inventory has ambiguous identities",
+        );
+      ids.add(check.id);
+      checks.push(check);
+    }
+    if (result.check_runs.length < 100)
+      return exactCheck(checks, run, host.repository);
+  }
+  throw new Error(
+    "Published entry check inventory exceeds its complete-read bound",
+  );
+}
+
+function exactCheck(checks, run, repository) {
+  const url = `https://github.com/${repository}/actions/runs/${run.id}/attempts/${run.run_attempt}`;
+  const matches = checks.filter(
+    (check) => check.name === "check" && check.details_url === url,
+  );
+  if (!matches.length) return null;
+  const values = matches.map((check) => {
+    const parsed =
+      /^buildchain:(attempt-[0-9a-f]{64}):([1-9][0-9]*):([1-9][0-9]*)$/u.exec(
+        check.external_id || "",
+      );
+    if (
+      !parsed ||
+      Number(parsed[2]) !== run.id ||
+      Number(parsed[3]) !== run.run_attempt ||
+      check.head_sha !== run.head_sha ||
+      check.status !== "completed" ||
+      !["success", "failure"].includes(check.conclusion) ||
+      check.app?.slug !== "github-actions"
+    )
+      throw new Error(
+        "Published entry check does not bind its exact native attempt",
+      );
+    return {
+      attempt: parsed[1],
+      outcome: check.conclusion,
+      summary: check.output?.summary || "",
+    };
+  });
+  if (values.some((value) => recordDigest(value) !== recordDigest(values[0])))
+    throw new Error("Published entry checks disagree about the same execution");
+  return {
+    ...values[0],
+    ids: matches.map(({ id }) => id).sort((a, b) => a - b),
+  };
+}

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

@@ -0,0 +1,52 @@
+import { readBusinessAttempt } from "../../workflow/attempt/reader.js";
+
+// Branch/terminal notifications wake existing intents only. They cannot create
+// historical releases or infer an execution request from an untracked old PR.
+export function githubPipelineEvents(request, journal, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline event repository");
+  const base = `/repos/${repository}`;
+  async function list(url) {
+    const rows = [];
+    for (let page = 1; page <= 100; page++) {
+      const entries = await request(
+        `${url}${url.includes("?") ? "&" : "?"}per_page=100&page=${page}`,
+      );
+      if (!Array.isArray(entries))
+        throw new Error("Invalid pipeline PR event readback");
+      rows.push(...entries);
+      if (entries.length < 100) return rows;
+    }
+    throw new Error("Pipeline PR event readback exceeds its bound");
+  }
+  async function branch(branch, commit = "") {
+    if (
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        branch || "",
+      ) ||
+      branch.includes("..")
+    )
+      throw new Error("Invalid pipeline branch event");
+    const pulls = await list(
+      `${base}/pulls?state=open&base=${encodeURIComponent(branch)}`,
+    );
+    if (commit) {
+      if (!/^[0-9a-f]{40}$/u.test(commit))
+        throw new Error("Branch wake requires exact source commit");
+      pulls.push(...(await list(`${base}/commits/${commit}/pulls`)));
+    }
+    const result = new Set();
+    for (const number of [
+      ...new Set(
+        pulls.filter((pr) => pr.base?.ref === branch).map((pr) => pr.number),
+      ),
+    ]) {
+      const retained = await journal.lookup(repository, number, branch);
+      if (!retained) continue;
+      const state = readBusinessAttempt(retained.snapshot);
+      if (state.attempt) result.add(state.attempt);
+    }
+    return [...result];
+  }
+  return { branch };
+}

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

@@ -0,0 +1,95 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelinePlatforms } from "../../workflow/pipeline/platforms.js";
+
+export function githubPipelineIntegration(request, repository, source, runs) {
+  const base = `/repos/${repository}`;
+  async function observe(current) {
+    const number = current.intent.source.pullRequest;
+    const branch = current.intent.source.targetBranch;
+    const pr = await request(`${base}/pulls/${number}`);
+    if (
+      !pr.merged ||
+      pr.head?.sha !== current.generation.source.commit ||
+      pr.base?.ref !== branch ||
+      pr.head?.repo?.full_name !== repository ||
+      pr.base?.repo?.full_name !== repository ||
+      !/^[0-9a-f]{40}$/u.test(pr.merge_commit_sha || "")
+    )
+      throw new Error(
+        "Integration needs the exact source PR merged into its protected target",
+      );
+    const mergeCommit = pr.merge_commit_sha;
+    const protectedHead = await source.branchHead(branch);
+    const ancestry = await request(
+      `${base}/compare/${mergeCommit}...${protectedHead}`,
+    );
+    if (
+      !["identical", "ahead"].includes(ancestry.status) ||
+      ancestry.merge_base_commit?.sha !== mergeCommit
+    )
+      throw new Error(
+        "Exact merge commit is not contained in the protected branch",
+      );
+    const commits = await source.source(
+      mergeCommit,
+      current.generation.source.configPath,
+    );
+    const response = await request(
+      `${base}/actions/runs?event=merge_group&head_sha=${mergeCommit}&per_page=100`,
+    );
+    if (!Array.isArray(response.workflow_runs) || response.total_count > 100)
+      throw new Error(
+        "Exact merge-group run inventory is unavailable or ambiguous",
+      );
+    const candidates = response.workflow_runs.filter(
+      (run) =>
+        run.status === "completed" &&
+        run.conclusion === "success" &&
+        run.path?.split("@")[0] === ".github/workflows/buildchain.yml",
+    );
+    if (!candidates.length)
+      throw new Error(
+        "Exact merged commit has no successful normal pipeline merge-group run",
+      );
+    const chosen = candidates.sort((a, b) => b.id - a.id)[0];
+    const { run } = await runs.read(chosen.id, chosen.run_attempt);
+    if (
+      run.status !== "completed" ||
+      run.conclusion !== "success" ||
+      run.event !== "merge_group" ||
+      run.head_sha !== mergeCommit
+    )
+      throw new Error("Integration merge-group execution changed");
+    const build = await runs.build(
+      run.id,
+      run.run_attempt,
+      commits.identity,
+      pipelinePlatforms(commits.plan).map((item) => item.platform),
+    );
+    if (build.outcome !== "success")
+      throw new Error("Exact merged tree product verification failed");
+    const again = await request(`${base}/pulls/${number}`);
+    if (
+      !again.merged ||
+      again.merge_commit_sha !== mergeCommit ||
+      again.head.sha !== pr.head.sha ||
+      again.base.ref !== branch
+    )
+      throw new Error("Integration provider source changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-integration-readback/v1",
+      repository,
+      pullRequest: number,
+      sourceHead: pr.head.sha,
+      branch,
+      protectedHead,
+      mergeCommit,
+      mergeTree: commits.identity.tree,
+      run,
+      build,
+      ancestry,
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  return { observe };
+}

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

@@ -0,0 +1,213 @@
+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){branchProtectionRule{requiresApprovingReviews requiredApprovingReviewCount requiresCodeOwnerReviews requiresStatusChecks requiredStatusChecks{context app{databaseId}}}}mergeQueue(branch:$branch){id}}}`;
+
+async function classicPolicy(request, owner, name, branch) {
+  // REST /branches/:branch/protection requires Administration:read. Ordinary
+  // workflow credentials instead read effective rules and GraphQL metadata.
+  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) throw new Error("Protected branch metadata is unavailable");
+  const rule = repository.ref?.branchProtectionRule;
+  return {
+    required_merge_queue: Boolean(repository.mergeQueue?.id),
+    required_pull_request_reviews: rule?.requiresApprovingReviews
+      ? {
+          require_code_owner_reviews: rule.requiresCodeOwnerReviews,
+          required_approving_review_count: rule.requiredApprovingReviewCount,
+        }
+      : null,
+    required_status_checks: {
+      checks: rule?.requiresStatusChecks
+        ? (rule.requiredStatusChecks || []).map((check) => ({
+            context: check.context,
+            app_id: check.app?.databaseId || null,
+          }))
+        : [],
+    },
+  };
+}
+
+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;
+}