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

package/packages/core/publication/pipeline/prepare.js

@@ -0,0 +1,139 @@
+import { claimPipelinePublicationWorker } from "./worker.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelinePlatforms } from "../../workflow/pipeline/platforms.js";
+import { githubPipelineVersion } from "../../providers/github/pipeline-version.js";
+import { createPipelinePublicationPlan } from "./source-plan.js";
+import { preparePipelineStableQualification } from "./stable-wait.js";
+import { prepareRecoveredPublication } from "./recovery-prepare.js";
+import {
+  preparePipelineVersionContext,
+  retainedPipelineVersionRegeneration,
+} from "./version-context.js";
+
+function publicationNextOperation(phase, existing, recovery) {
+  if (phase !== "publish") return "settle";
+  if (existing.length) return "apply";
+  if (recovery?.mode === "prepared" || recovery?.build?.scheduled.length === 0)
+    return "qualify";
+  return "build";
+}
+
+export async function preparePipelinePublication(attempt, publisherSha, host) {
+  const claimed = await claimPipelinePublicationWorker(
+    attempt,
+    publisherSha,
+    host,
+  );
+  if (!claimed) return { operation: "wait" };
+  const { session, journal, phase } = claimed;
+  const observed = session.observed;
+  const recovery = await prepareRecoveredPublication(
+    session,
+    publisherSha,
+    host,
+    journal,
+    phase,
+  );
+  const plans = await journal.materials("publication/plan/");
+  if (plans.length > 1)
+    throw new Error("Publication has conflicting retained plans");
+  const version = githubPipelineVersion(host.request, host.repository);
+  let plan = plans[0];
+  if (!plan) {
+    plan = await createPipelinePublicationPlan(
+      session,
+      publisherSha,
+      host,
+      version,
+    );
+    await journal.record("publication/plan", plan);
+  }
+  const wait = await preparePipelineStableQualification(plan, host, journal, {
+    attempt,
+    generation: observed.generation,
+    phase,
+  });
+  if (wait) return { operation: "wait", wait };
+  if (
+    !recovery &&
+    (plan.publisher.workflowSha !== publisherSha ||
+      plan.runtime.commit !== host.runtime.sha)
+  )
+    throw new Error(
+      "Publication resume requires its retained publisher and runtime; use typed recovery for upgrades",
+    );
+  const materializations = await journal.materials(
+    "publication/materialization/",
+  );
+  if (materializations.length > 1)
+    throw new Error("Publication materialized source is ambiguous");
+  let materialization = materializations[0];
+  if (!materialization) {
+    const regeneration = await retainedPipelineVersionRegeneration(
+      journal,
+      plan,
+      "publication",
+      host.runtime,
+    );
+    if (plan.versionPolicy.derived_files?.length && !regeneration) {
+      const publication = {
+        attempt,
+        generation: observed.generation,
+        plan,
+        ...(recovery ? { recovery } : {}),
+      };
+      return {
+        operation: "regenerate",
+        context: await preparePipelineVersionContext(
+          plan,
+          "publication",
+          publication,
+          host,
+          journal,
+          publisherSha,
+        ),
+      };
+    }
+    await journal.fence();
+    materialization = await version.materialize(plan, regeneration);
+    const verified = await host.source.source(
+      materialization.source.commit,
+      plan.source.configPath,
+    );
+    if (recordDigest(verified.plan) !== plan.contractRoot)
+      throw new Error("Version materialization altered the product contract");
+    const { root, ...body } = materialization;
+    materialization = { ...body, source: verified.identity };
+    materialization.root = recordDigest(materialization);
+    await journal.record("publication/materialization", materialization);
+  }
+  const admitted = await host.source.source(
+    materialization.source.commit,
+    plan.source.configPath,
+  );
+  if (
+    recordDigest(admitted.identity) !== recordDigest(materialization.source) ||
+    recordDigest(admitted.plan) !== plan.contractRoot
+  )
+    throw new Error("Retained publication source or contract drifted");
+  const existing = await journal.materials("publication/qualified/");
+  const context = {
+    schema: "buildchain.pipeline-publication-context/v1",
+    attempt,
+    generation: observed.generation,
+    plan,
+    materialization,
+    platforms: pipelinePlatforms(admitted.plan).filter(
+      ({ platform }) =>
+        !recovery?.build || recovery.build.scheduled.includes(platform),
+    ),
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    ...(recovery ? { recovery } : {}),
+  };
+  await journal.record("publication/context", context, { phase });
+  return {
+    operation: publicationNextOperation(phase, existing, recovery),
+    context,
+  };
+}

package/packages/core/publication/pipeline/qualification.js

@@ -0,0 +1,175 @@
+import {
+  PUBLICATION_BUILD_AGGREGATE,
+  publicationArtifactProducer,
+  verifyPublicationBuildAggregate,
+} from "./build-segments.js";
+import path from "node:path";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { createDomainPublicationQualificationReceipt } from "../publication-qualification.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import {
+  inspectPipelineFileArtifact,
+  verifyPipelineProductFiles,
+} from "./pack.js";
+import { publicationPath } from "./files.js";
+import { assertPipelinePackagePolicy } from "./package-policy.js";
+import { readNpmPackageJsonFromTarball } from "../../release/candidate/payloads.js";
+
+function productDescriptor(artifact) {
+  const { file, size, digest, package: pkg, ...descriptor } = artifact;
+  return descriptor;
+}
+
+export function inspectPipelinePublicationArtifacts(directory, manifest, plan) {
+  verifyPipelineProductFiles(directory, manifest);
+  for (const artifact of manifest.artifacts) {
+    if (artifact.filename && path.basename(artifact.file) !== artifact.filename)
+      throw new Error(
+        "Independent qualification rejected the declared download filename",
+      );
+    if (artifact.kind === "npm-package") {
+      const pkg = readNpmPackageJsonFromTarball(
+        publicationPath(directory, artifact.file),
+      );
+      assertPipelinePackagePolicy(pkg);
+      if (
+        !artifact.package ||
+        pkg.name !== artifact.package.name ||
+        pkg.version !== plan.version ||
+        pkg.version !== artifact.package.version ||
+        pkg.private === true
+      )
+        throw new Error(
+          "Independent npm qualification rejected package identity or version",
+        );
+    } else
+      inspectPipelineFileArtifact(directory, {
+        path: artifact.file,
+        kind: artifact.kind,
+      });
+  }
+}
+
+export function qualifyPipelineProducts({
+  plan,
+  source,
+  bundles,
+  build,
+  policyRoot,
+  now = new Date(),
+}) {
+  verifyPipelinePublicationPlan(plan);
+  if (build.schema === PUBLICATION_BUILD_AGGREGATE)
+    verifyPublicationBuildAggregate(build, {
+      plan,
+      materialization: { source },
+      runId: build.runId,
+      runAttempt: build.runAttempt,
+    });
+  const { root: buildRoot, ...buildBody } = build;
+  if (
+    buildRoot !== recordDigest(buildBody) ||
+    !Number.isSafeInteger(build.runId) ||
+    build.runId < 1 ||
+    ![
+      "buildchain.pipeline-publication-build-readback/v1",
+      PUBLICATION_BUILD_AGGREGATE,
+    ].includes(build.schema) ||
+    build.outcome !== "success" ||
+    build.planRoot !== plan.root ||
+    recordDigest(build.source) !== recordDigest(source)
+  )
+    throw new Error(
+      "Publication requires exact independent completed build readback",
+    );
+  const platforms = [
+    ...new Set(plan.outputs.map(({ platform }) => platform)),
+  ].sort();
+  const observed = bundles.map(({ manifest }) => manifest.platform).sort();
+  if (
+    recordDigest(platforms) !== recordDigest(observed) ||
+    recordDigest(platforms) !== recordDigest(build.platforms)
+  )
+    throw new Error(
+      "Publication build must cover exactly every declared platform",
+    );
+  const artifactIds = bundles
+    .map(({ providerArtifact }) => providerArtifact.id)
+    .sort((left, right) => left - right);
+  if (
+    new Set(artifactIds).size !== platforms.length ||
+    recordDigest(artifactIds) !== recordDigest(build.artifactIds)
+  )
+    throw new Error(
+      "Publication readback must cover exactly the retained provider artifacts",
+    );
+  const descriptors = [],
+    artifacts = [];
+  for (const { directory, manifest, providerArtifact } of bundles) {
+    const producer = publicationArtifactProducer(build, providerArtifact.id);
+    if (
+      manifest.planRoot !== producer.build.planRoot ||
+      recordDigest(manifest.source) !== recordDigest(source) ||
+      !build.artifactIds.includes(providerArtifact.id) ||
+      providerArtifact.expired ||
+      providerArtifact.workflow_run?.id !== producer.build.runId
+    )
+      throw new Error(
+        "Publication artifact is not bound to the exact admitted source run",
+      );
+    inspectPipelinePublicationArtifacts(directory, manifest, plan);
+    descriptors.push(...manifest.artifacts.map(productDescriptor));
+    artifacts.push(
+      ...manifest.artifacts.map((artifact) => ({
+        ...artifact,
+        manifestRoot: manifest.root,
+        providerArtifactId: providerArtifact.id,
+      })),
+    );
+  }
+  descriptors.sort((left, right) => left.id.localeCompare(right.id));
+  artifacts.sort((left, right) => left.id.localeCompare(right.id));
+  if (recordDigest(descriptors) !== recordDigest(plan.outputs))
+    throw new Error(
+      "Publication artifacts do not exactly match declared outputs and targets",
+    );
+  if (new Set(artifacts.map(({ file }) => file)).size !== artifacts.length)
+    throw new Error("Publication asset filenames must be unique");
+  const packages = artifacts.filter((artifact) => artifact.package);
+  if (
+    new Set(packages.map(({ package: pkg }) => pkg.name)).size !==
+    packages.length
+  )
+    throw new Error(
+      "Multi-platform npm publication requires distinct declared package names",
+    );
+  const candidateRoot = recordDigest({
+    planRoot: plan.root,
+    source,
+    artifacts,
+  });
+  const qualification = createDomainPublicationQualificationReceipt({
+    repository: source.repository,
+    candidateRoot,
+    sourceSha: source.commit,
+    sourceRoot: recordDigest(source),
+    policyDigest: policyRoot,
+    artifacts: artifacts.map((artifact) => ({
+      role: `${artifact.product}/${artifact.artifact}`,
+      platform: artifact.platform,
+      artifactRoot: artifact.digest,
+      manifestRoot: artifact.manifestRoot,
+    })),
+    issuedAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + 60 * 60 * 1000).toISOString(),
+  });
+  const body = {
+    schema: "buildchain.pipeline-publication-qualification/v1",
+    planRoot: plan.root,
+    source,
+    build,
+    artifacts,
+    qualification,
+  };
+  return { ...body, root: recordDigest(body) };
+}

package/packages/core/publication/pipeline/qualify.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { githubPipelinePublicationArtifacts } from "../../providers/github/pipeline-publication-artifacts.js";
+import { publicationContext, uniquePublicationMaterial } from "./context.js";
+import { qualifyPipelineProducts } from "./qualification.js";
+import { pipelineProductCapsules } from "./capsules.js";
+import { retainPipelineProducts } from "./sealed-products.js";
+import { preparePipelineSigning, verifyPipelineSigning } from "./signing.js";
+import { pipelineReleaseDocuments } from "./documents.js";
+import { downloadRecoveryPublicationBuild } from "./recovery-build-download.js";
+import { prepareRecoveredSigning } from "./recovery-signing.js";
+
+export async function preparePipelineQualification(context, host, directory) {
+  const { journal, archive } = await publicationContext(context, host);
+  if (context.recovery?.mode === "prepared")
+    return prepareRecoveredSigning(context, host, journal, archive, directory);
+  const products = githubPipelinePublicationArtifacts(host);
+  const productDirectory = path.join(directory, "products");
+  const { build, bundles } = context.recovery?.build
+    ? await downloadRecoveryPublicationBuild(context, host, productDirectory)
+    : await products.download(context, productDirectory);
+  const { plan, materialization } = context;
+  const qualified = qualifyPipelineProducts({
+    plan,
+    source: materialization.source,
+    bundles,
+    build,
+    policyRoot: plan.contractRoot,
+  });
+  const capsules = pipelineProductCapsules({
+    plan,
+    materialization,
+    qualified,
+    bundles,
+  });
+  const sealed = await retainPipelineProducts(archive, qualified, bundles);
+  const prepared = {
+    schema: "buildchain.pipeline-qualification-preparation/v1",
+    contextRoot: recordDigest(context),
+    qualified,
+    capsules,
+    sealed,
+  };
+  await journal.fence();
+  await journal.record(
+    `publication/qualification-prepared/${context.runId}-${context.runAttempt}`,
+    prepared,
+  );
+  return preparePipelineSigning({
+    plan,
+    materialization,
+    qualified,
+    directory: path.join(directory, "signing"),
+  });
+}
+
+export async function sealPipelineQualification(
+  context,
+  host,
+  directory,
+  bundlePath,
+) {
+  const { journal, archive } = await publicationContext(context, host);
+  const prepared = await uniquePublicationMaterial(
+    journal,
+    `publication/qualification-prepared/${context.runId}-${context.runAttempt}/`,
+  );
+  if (prepared.contextRoot !== recordDigest(context))
+    throw new Error("Signing preparation changed provider context");
+  const { plan, materialization } = context;
+  const signing = verifyPipelineSigning({
+    plan,
+    materialization,
+    qualified: prepared.qualified,
+    directory: path.join(directory, "verify-signing"),
+    bundlePath,
+    token: host.token,
+  });
+  const bundle = await archive.put(fs.readFileSync(bundlePath), {
+    name: "attestation.json",
+    mediaType: "application/json",
+  });
+  if (bundle.digest !== signing.bundleDigest)
+    throw new Error("Retained attestation differs from verified signing bytes");
+  await archive.read(bundle);
+  const documents = pipelineReleaseDocuments({
+    plan,
+    materialization,
+    qualified: prepared.qualified,
+    capsules: prepared.capsules,
+    signing,
+  });
+  const result = {
+    ...prepared,
+    schema: "buildchain.pipeline-qualified-products/v1",
+    signing,
+    bundle,
+    documents,
+  };
+  await journal.fence();
+  await journal.record("publication/qualified", result);
+  return result;
+}

package/packages/core/publication/pipeline/recovery-admission.js

@@ -0,0 +1,122 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  createReleaseInvocation,
+  createReleaseReceipt,
+  RELEASE_RECEIPT_CONTRACT,
+} from "../../release/release-invocation.js";
+import {
+  createDomainPublicationQualificationReceipt,
+  validatePublicationQualificationReceipt,
+} from "../publication-qualification.js";
+import { verifyPipelineQualification } from "./documents.js";
+
+export const RECOVERY_PUBLICATION_ADMISSION =
+  "buildchain.pipeline-recovery-publication-admission/v1";
+
+// Only the publisher's byte/signature/provider requalification calls this pure
+// domain bridge. It creates fresh authority for the new execution and preserves
+// the original invocation, transaction, Passport and qualification unchanged.
+export function createRecoveryPublicationAdmission({
+  context,
+  retained,
+  execution,
+  readback,
+  now = new Date(),
+}) {
+  const { plan, materialization } = context;
+  const { qualified, documents } = retained;
+  const { root, ...body } = readback;
+  if (
+    !context.recovery ||
+    !/^sha256:[0-9a-f]{64}$/u.test(context.recovery.planRoot || "") ||
+    context.recovery.predecessor === context.attempt ||
+    execution.attempt !== context.attempt ||
+    execution.runId !== context.runId ||
+    execution.runAttempt !== context.runAttempt ||
+    body.schema !== "buildchain.pipeline-recovery-publication-readback/v1" ||
+    root !== recordDigest(body) ||
+    body.transactionRoot !== documents.transaction.transactionRoot ||
+    body.qualificationRoot !== qualified.root ||
+    body.signingRoot !== recordDigest(retained.signing) ||
+    body.sealedRoot !== retained.sealed.root
+  )
+    throw new Error(
+      "Recovery publication admission requires exact current execution and independent retained-byte readback",
+    );
+  verifyPipelineQualification({
+    plan,
+    materialization,
+    qualified,
+    evaluatedAt: qualified.qualification.issuedAt,
+  });
+  const qualification = createDomainPublicationQualificationReceipt({
+    ...qualified.qualification,
+    issuedAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + 60 * 60 * 1000).toISOString(),
+  });
+  // This observation reports the predecessor transaction at the recovery
+  // boundary. It is not a replacement for any original terminal receipt.
+  const predecessorReceipt = createReleaseReceipt({
+    schema: RELEASE_RECEIPT_CONTRACT,
+    transactionRoot: documents.transaction.transactionRoot,
+    outcome: "blocked",
+    releasePassportRoot: documents.passport.passportRoot,
+    providerTransactionRoot: body.effectsRoot,
+    providerStateRoot: readback.root,
+    providerReceiptRoots: [...new Set(body.receiptRoots)].sort(),
+  });
+  const invocation = createReleaseInvocation({
+    ...documents.invocation.invocation,
+    publisher: execution.publisher,
+    runtime: execution.runtime,
+    authority: {
+      policyRoot: plan.contractRoot,
+      qualificationRoot: qualification.receiptRoot,
+      warrantRoot: qualification.receiptRoot,
+    },
+    parent: {
+      invocationRoot: documents.invocation.roots.invocationRoot,
+      transactionRoot: documents.transaction.transactionRoot,
+      receiptRoot: predecessorReceipt.receiptRoot,
+    },
+  });
+  const value = {
+    schema: RECOVERY_PUBLICATION_ADMISSION,
+    contextRoot: recordDigest(context),
+    recoveryPlanRoot: context.recovery.planRoot,
+    execution,
+    originalDocumentsRoot: recordDigest(documents),
+    readbackRoot: readback.root,
+    qualification,
+    predecessorReceipt,
+    invocation,
+  };
+  return { ...value, root: recordDigest(value) };
+}
+
+export function verifyRecoveryPublicationAdmission(
+  admission,
+  { context, retained, execution, readback, now = new Date() },
+) {
+  const expected = createRecoveryPublicationAdmission({
+    context,
+    retained,
+    execution,
+    readback,
+    now: new Date(admission.qualification.issuedAt),
+  });
+  if (recordDigest(expected) !== recordDigest(admission))
+    throw new Error(
+      "Recovery publication authority changed its exact execution or original transaction",
+    );
+  validatePublicationQualificationReceipt(admission.qualification, {
+    repository: context.plan.source.repository,
+    candidateRoot: retained.qualified.qualification.candidateRoot,
+    sourceSha: retained.qualified.source.commit,
+    sourceRoot: recordDigest(retained.qualified.source),
+    artifactRoot: retained.qualified.qualification.artifactRoot,
+    policyDigest: context.plan.contractRoot,
+    evaluatedAt: now.toISOString(),
+  });
+  return admission;
+}

package/packages/core/publication/pipeline/recovery-build-download.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { qualifyRecoveryRuntime } from "../../workflow/pipeline/recovery-runtime.js";
+import { githubPipelinePublicationArtifacts } from "../../providers/github/pipeline-publication-artifacts.js";
+import { qualifyPublicationBuildSegments } from "./build-segments.js";
+
+export async function downloadRecoveryPublicationBuild(
+  context,
+  host,
+  directory,
+) {
+  const recovery = context.recovery.build;
+  const { root, ...body } = recovery;
+  if (
+    root !== recordDigest(body) ||
+    recordDigest(recovery.source) !==
+      recordDigest(context.materialization.source)
+  )
+    throw new Error(
+      "Recovery publication build changed its retained source evidence",
+    );
+  const provider = githubPipelinePublicationArtifacts(host),
+    segments = [],
+    bundles = [];
+  for (const [index, segment] of recovery.segments.entries()) {
+    const comparison = await qualifyRecoveryRuntime(
+      segment.runtime,
+      host.runtime,
+      "publication-build",
+      host.request,
+    );
+    if (!comparison.compatible)
+      throw new Error(
+        "Recovered publication producer changed after runtime admission",
+      );
+    const original = {
+      plan: segment.plan,
+      materialization: segment.materialization,
+      runId: segment.build.runId,
+      runAttempt: segment.build.runAttempt,
+    };
+    const downloaded = await provider.download(
+      original,
+      path.join(directory, `predecessor-${index}`),
+      segment.build.platforms,
+    );
+    if (recordDigest(downloaded.build) !== recordDigest(segment.build))
+      throw new Error(
+        "Recovered publication artifact evidence changed after admission",
+      );
+    segments.push(segment);
+    bundles.push(...downloaded.bundles);
+  }
+  if (recovery.scheduled.length) {
+    const downloaded = await provider.download(
+      context,
+      path.join(directory, "current"),
+      recovery.scheduled,
+    );
+    segments.push({
+      plan: context.plan,
+      materialization: context.materialization,
+      runtime: host.runtime,
+      build: downloaded.build,
+    });
+    bundles.push(...downloaded.bundles);
+  }
+  const { run } = await host.runs.read(context.runId, context.runAttempt);
+  await readPipelineCaller(
+    run,
+    context.materialization.source.configPath,
+    host.request,
+    host.repository,
+  );
+  return {
+    build: qualifyPublicationBuildSegments(context, segments, run.head_sha),
+    bundles,
+  };
+}