@kungfu-tech/buildchain 3.0.5-alpha.7 → 3.0.5

package/packages/core/release-propagation-pickup.js

@@ -1,386 +0,0 @@
-import {
-  assertExactFields,
-  assertPlainObject,
-  assertString,
-  normalizeChannel,
-  optionalString,
-} from "./release-propagation-common.js";
-import { normalizeExecutionProfile } from "./release-propagation-execution-profile.js";
-import { assertCommitSha } from "./release-propagation-work-control.js";
-import {
-  createReleasePropagationWork,
-  planReleasePropagation,
-} from "./release-propagation.js";
-import { normalizeUpstreamRelease } from "./release-propagation-release.js";
-
-export const MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT =
-  "kungfu-buildchain-manual-upstream-pickup";
-export const MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT =
-  "kungfu-buildchain-manual-upstream-pickup-plan";
-
-function assertRepository(value, label) {
-  const repository = assertString(value, label);
-  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
-    throw new Error(`${label} must be owner/repo`);
-  }
-  return repository;
-}
-
-function normalizeStringList(values, label) {
-  if (!Array.isArray(values) || values.length === 0) {
-    throw new Error(`${label} must be a non-empty array`);
-  }
-  const normalized = values.map((value, index) =>
-    assertString(value, `${label}[${index}]`),
-  );
-  const canonical = [...new Set(normalized)].sort();
-  if (JSON.stringify(normalized) !== JSON.stringify(canonical)) {
-    throw new Error(`${label} must be sorted and unique`);
-  }
-  return canonical;
-}
-
-function normalizeRuntime(value) {
-  const runtime = assertExactFields(
-    value,
-    ["package", "version"],
-    "manual pickup runtime",
-  );
-  return {
-    package: assertString(runtime.package, "manual pickup runtime.package"),
-    version: assertString(runtime.version, "manual pickup runtime.version"),
-  };
-}
-
-function normalizeDownstream(value) {
-  const downstream = assertExactFields(
-    value,
-    ["id", "repository", "baseRef", "executionProfile"],
-    "manual pickup downstream",
-  );
-  return {
-    id: assertString(downstream.id, "manual pickup downstream.id"),
-    repository: assertRepository(
-      downstream.repository,
-      "manual pickup downstream.repository",
-    ),
-    baseRef: assertString(
-      downstream.baseRef,
-      "manual pickup downstream.baseRef",
-    ),
-    executionProfile: normalizeExecutionProfile(
-      downstream.executionProfile,
-      "manual pickup downstream.executionProfile",
-    ),
-  };
-}
-
-function normalizeSource(value, index) {
-  const label = `manual pickup sources[${index}]`;
-  const source = assertExactFields(
-    value,
-    [
-      "id",
-      "repository",
-      "package",
-      "lockPath",
-      "distTags",
-      "workflowPaths",
-      "workflowRefs",
-    ],
-    label,
-  );
-  const distTags = assertExactFields(
-    source.distTags,
-    ["alpha", "release"],
-    `${label}.distTags`,
-  );
-  return {
-    id: assertString(source.id, `${label}.id`),
-    repository: assertRepository(source.repository, `${label}.repository`),
-    package: assertString(source.package, `${label}.package`),
-    lockPath: assertString(source.lockPath, `${label}.lockPath`),
-    distTags: {
-      alpha: assertString(distTags.alpha, `${label}.distTags.alpha`),
-      release: assertString(distTags.release, `${label}.distTags.release`),
-    },
-    workflowPaths: normalizeStringList(
-      source.workflowPaths,
-      `${label}.workflowPaths`,
-    ),
-    workflowRefs: normalizeStringList(
-      source.workflowRefs,
-      `${label}.workflowRefs`,
-    ),
-  };
-}
-
-export function normalizeManualUpstreamPickupConfig(input) {
-  const config = assertExactFields(
-    input,
-    ["schemaVersion", "contract", "runtime", "downstream", "sources"],
-    "manual upstream pickup config",
-  );
-  if (
-    config.schemaVersion !== 1 ||
-    config.contract !== MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT
-  ) {
-    throw new Error(
-      `manual upstream pickup config must use ${MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT} v1`,
-    );
-  }
-  if (!Array.isArray(config.sources) || config.sources.length === 0) {
-    throw new Error(
-      "manual upstream pickup config sources must be a non-empty array",
-    );
-  }
-  const sources = config.sources.map(normalizeSource);
-  const ids = sources.map((source) => source.id);
-  if (new Set(ids).size !== ids.length)
-    throw new Error("manual pickup source ids must be unique");
-  return {
-    schemaVersion: 1,
-    contract: MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT,
-    runtime: normalizeRuntime(config.runtime),
-    downstream: normalizeDownstream(config.downstream),
-    sources,
-  };
-}
-
-function decodePayload(attestation, label) {
-  const encoded = attestation?.bundle?.dsseEnvelope?.payload;
-  if (!encoded) throw new Error(`${label} is missing a DSSE payload`);
-  try {
-    return JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
-  } catch {
-    throw new Error(`${label} DSSE payload is not valid JSON`);
-  }
-}
-
-function repositoryFromUrl(value) {
-  return String(value || "")
-    .replace(/^git\+/, "")
-    .replace(/^https:\/\/github\.com\//, "")
-    .replace(/\.git$/, "");
-}
-
-export function resolveNpmRegistryRelease({
-  source: sourceInput,
-  channel,
-  packageMetadata,
-  attestations,
-}) {
-  const source = normalizeSource(sourceInput, 0);
-  const normalizedChannel = normalizeChannel(channel, "manual pickup channel");
-  const metadata = assertPlainObject(packageMetadata, "npm package metadata");
-  if (metadata.name !== source.package)
-    throw new Error("npm package name disagrees with manual pickup source");
-  if (
-    repositoryFromUrl(metadata.repository?.url || metadata.repository) !==
-    source.repository
-  ) {
-    throw new Error(
-      "npm package repository disagrees with manual pickup source",
-    );
-  }
-  const version = assertString(
-    metadata.version,
-    "npm package metadata.version",
-  );
-  const integrity = assertString(
-    metadata.dist?.integrity,
-    "npm package metadata.dist.integrity",
-  );
-  const attestationUrl = assertString(
-    metadata.dist?.attestations?.url,
-    "npm package metadata.dist.attestations.url",
-  );
-  const response = assertPlainObject(attestations, "npm attestations response");
-  const slsa = (response.attestations || []).find(
-    (entry) => entry.predicateType === "https://slsa.dev/provenance/v1",
-  );
-  if (!slsa) throw new Error("npm package does not expose SLSA provenance v1");
-  const statement = decodePayload(slsa, "npm SLSA provenance");
-  if (statement.predicateType !== "https://slsa.dev/provenance/v1") {
-    throw new Error(
-      "npm SLSA statement predicate type disagrees with its envelope",
-    );
-  }
-  const expectedSubject = `pkg:npm/${encodeURIComponent(source.package)}@${version}`;
-  const subject = (statement.subject || []).find(
-    (entry) => entry.name === expectedSubject,
-  );
-  if (!subject?.digest?.sha512)
-    throw new Error("npm SLSA provenance is missing the exact package subject");
-  const workflow =
-    statement.predicate?.buildDefinition?.externalParameters?.workflow || {};
-  const workflowRepository = repositoryFromUrl(workflow.repository);
-  if (workflowRepository !== source.repository) {
-    throw new Error(
-      "npm SLSA workflow repository disagrees with manual pickup source",
-    );
-  }
-  if (!source.workflowPaths.includes(workflow.path)) {
-    throw new Error(
-      "npm SLSA workflow path is not admitted by the manual pickup source",
-    );
-  }
-  if (!source.workflowRefs.includes(workflow.ref)) {
-    throw new Error(
-      "npm SLSA workflow ref is not admitted by the manual pickup source",
-    );
-  }
-  const dependency = (
-    statement.predicate?.buildDefinition?.resolvedDependencies || []
-  ).find(
-    (entry) =>
-      repositoryFromUrl(String(entry.uri || "").split("@")[0]) ===
-      source.repository,
-  );
-  const sourceSha = assertCommitSha(
-    dependency?.digest?.gitCommit,
-    "npm SLSA source commit",
-  );
-  const runUrl = assertString(
-    statement.predicate?.runDetails?.metadata?.invocationId,
-    "npm SLSA invocation URL",
-  );
-  return normalizeUpstreamRelease({
-    repository: source.repository,
-    channel: normalizedChannel,
-    tag: "",
-    tagTargetSha: "",
-    sourceSha,
-    package: {
-      name: source.package,
-      version,
-      integrity,
-      gitHead: optionalString(metadata.gitHead),
-    },
-    registryProvenance: {
-      registry: "https://registry.npmjs.org",
-      attestationUrl,
-      predicateType: slsa.predicateType,
-      subjectSha512: subject.digest.sha512,
-      repository: source.repository,
-      sourceSha,
-      workflowPath: workflow.path,
-      workflowRef: workflow.ref,
-      runUrl,
-    },
-  });
-}
-
-function pickupGraph(config, source) {
-  return {
-    schemaVersion: 1,
-    contract: "kungfu-buildchain-release-propagation-graph",
-    nodes: [
-      { id: source.id, repository: source.repository, package: source.package },
-      {
-        id: config.downstream.id,
-        repository: config.downstream.repository,
-        baseRef: config.downstream.baseRef,
-        lockPath: source.lockPath,
-        executionProfile: config.downstream.executionProfile,
-      },
-    ],
-    edges: [
-      {
-        id: `${source.id}-manual-pickup`,
-        from: source.id,
-        to: config.downstream.id,
-        channels: ["alpha", "release"],
-        channelPolicy: "preserve",
-        lockPath: source.lockPath,
-        prBaseRef: config.downstream.baseRef,
-      },
-    ],
-  };
-}
-
-export function createManualUpstreamPickupPlan({
-  config: configInput,
-  sourceId,
-  channel,
-  currentVersion,
-  upstreamRelease,
-}) {
-  const config = normalizeManualUpstreamPickupConfig(configInput);
-  const source = config.sources.find((entry) => entry.id === sourceId);
-  if (!source)
-    throw new Error(`manual pickup source is not configured: ${sourceId}`);
-  const release = normalizeUpstreamRelease(upstreamRelease);
-  const normalizedChannel = normalizeChannel(channel, "manual pickup channel");
-  if (
-    release.repository !== source.repository ||
-    release.package?.name !== source.package
-  ) {
-    throw new Error("manual pickup release disagrees with the selected source");
-  }
-  if (release.channel !== normalizedChannel)
-    throw new Error("manual pickup release channel disagrees with the request");
-  const installedVersion = assertString(
-    currentVersion,
-    "manual pickup currentVersion",
-  );
-  const status =
-    installedVersion === release.package.version
-      ? "current"
-      : "update-available";
-  const propagationPlan =
-    status === "current"
-      ? null
-      : planReleasePropagation({
-          graph: pickupGraph(config, source),
-          upstreamRelease: release,
-          sourceNode: source.id,
-        });
-  return {
-    schemaVersion: 1,
-    contract: MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT,
-    invocation: "downstream-manual",
-    automaticTrigger: false,
-    runtime: config.runtime,
-    source: {
-      id: source.id,
-      repository: source.repository,
-      package: source.package,
-      channel: normalizedChannel,
-      distTag: source.distTags[normalizedChannel],
-    },
-    currentVersion: installedVersion,
-    resolvedVersion: release.package.version,
-    status,
-    upstreamRelease: release,
-    propagationPlan,
-  };
-}
-
-export function createManualUpstreamPickupCapture({
-  plan,
-  expectedDownstreamBaseSha,
-}) {
-  const pickup = assertPlainObject(plan, "manual pickup plan");
-  if (
-    pickup.contract !== MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT ||
-    pickup.schemaVersion !== 1
-  ) {
-    throw new Error("manual pickup plan must use the v1 contract");
-  }
-  if (pickup.status === "current") {
-    return { plan: pickup, work: null, nextAction: "none" };
-  }
-  if (pickup.status !== "update-available" || !pickup.propagationPlan) {
-    throw new Error("manual pickup plan has an invalid status");
-  }
-  const expectedBaseSha = assertCommitSha(
-    expectedDownstreamBaseSha,
-    "expectedDownstreamBaseSha",
-  );
-  const work = createReleasePropagationWork({
-    plan: pickup.propagationPlan,
-    expectedDownstreamBaseSha: expectedBaseSha,
-  });
-  return { plan: pickup, work, nextAction: "claim" };
-}

package/packages/core/workflow-call-contract.js

@@ -1,308 +0,0 @@
-import crypto from "node:crypto";
-import { parseWorkflowDocument } from "./workflow-yaml-contract.js";
-
-export const WORKFLOW_CALL_CONTRACT =
-  "kungfu-buildchain-workflow-call-contract/v1";
-export const WORKFLOW_CALL_RECEIPT =
-  "kungfu-buildchain-workflow-call-receipt/v1";
-
-function stableJson(value) {
-  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value)
-      .sort()
-      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function sha256(value) {
-  return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
-}
-
-function exactSha(value) {
-  return /^[0-9a-f]{40}$/.test(String(value || "").toLowerCase());
-}
-
-function coordinate(uses) {
-  const match = String(uses || "").match(
-    /^([^/]+\/[^/]+)\/(\.github\/workflows\/[^@]+)@([^@]+)$/,
-  );
-  return match ? { repository: match[1], path: match[2], ref: match[3] } : null;
-}
-
-function permissionLevel(value) {
-  if (value === "write" || value === "write-all") return 2;
-  if (value === "read" || value === "read-all") return 1;
-  if (value === "none" || value === "{}") return 0;
-  return -1;
-}
-
-function callerPermission(permissions, name) {
-  return permissions[name] || permissions["*"] || "none";
-}
-
-function validatePermissions(caller, callee) {
-  const failures = [];
-  for (const [name, required] of Object.entries(callee)) {
-    if (name === "*") continue;
-    const available = callerPermission(caller, name);
-    if (
-      permissionLevel(required) < 0 ||
-      permissionLevel(available) < permissionLevel(required)
-    ) {
-      failures.push({
-        code: "permission-drift",
-        message: `caller permission ${name}=${available} does not satisfy callee ${required}`,
-      });
-    }
-  }
-  return failures;
-}
-
-function validateInputs(job, reusable) {
-  const failures = [];
-  const declared = new Map(reusable.inputs.map((entry) => [entry.name, entry]));
-  for (const [name, supplied] of Object.entries(job.with)) {
-    const input = declared.get(name);
-    if (!input) {
-      failures.push({
-        code: "undeclared-input",
-        message: `caller supplies undeclared input: ${name}`,
-      });
-      continue;
-    }
-    if (supplied.kind !== "expression" && supplied.kind !== input.type) {
-      failures.push({
-        code: "input-type-drift",
-        message: `caller input ${name} is ${supplied.kind}, callee requires ${input.type}`,
-      });
-    }
-  }
-  for (const input of reusable.inputs.filter((entry) => entry.required)) {
-    if (!(input.name in job.with)) {
-      failures.push({
-        code: "missing-required-input",
-        message: `caller omits required input: ${input.name}`,
-      });
-    }
-  }
-  return failures;
-}
-
-function validateSecrets(job, reusable) {
-  if (job.secrets === "inherit") {
-    return [
-      {
-        code: "secret-inheritance-not-exact",
-        message:
-          "secrets: inherit cannot prove an exact reusable-workflow secret contract",
-      },
-    ];
-  }
-  const failures = [];
-  const declared = new Map(
-    reusable.secrets.map((entry) => [entry.name, entry]),
-  );
-  for (const name of Object.keys(job.secrets)) {
-    if (!declared.has(name)) {
-      failures.push({
-        code: "undeclared-secret",
-        message: `caller supplies undeclared secret: ${name}`,
-      });
-    }
-  }
-  for (const secret of reusable.secrets.filter((entry) => entry.required)) {
-    if (!(secret.name in job.secrets)) {
-      failures.push({
-        code: "missing-required-secret",
-        message: `caller omits required secret: ${secret.name}`,
-      });
-    }
-  }
-  return failures;
-}
-
-function validateEvents(actual, trusted) {
-  const trustedSet = new Set(trusted);
-  return actual
-    .filter((event) => !trustedSet.has(event))
-    .map((event) => ({
-      code: "untrusted-event-drift",
-      message: `caller admits untrusted event class: ${event}`,
-    }));
-}
-
-function interfaceProjection(reusable) {
-  return {
-    inputs: reusable.inputs,
-    secrets: reusable.secrets,
-    outputs: reusable.outputs,
-    permissions: reusable.permissions,
-  };
-}
-
-function validateCoordinate(job, { repository, workflowPath, sha }) {
-  const failures = [];
-  const pinned = coordinate(job?.uses);
-  if (!pinned) {
-    return [
-      {
-        code: "callee-coordinate-invalid",
-        message:
-          "caller uses must name owner/repo/.github/workflows/file.yml@ref",
-      },
-    ];
-  }
-  if (!exactSha(pinned.ref)) {
-    failures.push({
-      code: "floating-callee-ref",
-      message: `callee ref is not an exact commit SHA: ${pinned.ref}`,
-    });
-  }
-  if (pinned.repository !== repository || pinned.path !== workflowPath) {
-    failures.push({
-      code: "callee-coordinate-drift",
-      message: `caller uses ${pinned.repository}/${pinned.path}, expected ${repository}/${workflowPath}`,
-    });
-  }
-  if (pinned.ref.toLowerCase() !== String(sha || "").toLowerCase()) {
-    failures.push({
-      code: "stale-pinned-ref",
-      message: `caller pin ${pinned.ref} does not match checked callee ${sha}`,
-    });
-  }
-  return failures;
-}
-
-export function evaluateWorkflowCallContract({
-  callerText,
-  calleeText,
-  callerRepository,
-  callerWorkflowPath,
-  callerSha,
-  callerTree,
-  callerSourceState = "clean",
-  calleeRepository,
-  calleeWorkflowPath,
-  calleeSha,
-  jobId,
-  trustedEventClasses = [],
-  expectedContractRoot = "",
-} = {}) {
-  const caller = parseWorkflowDocument(callerText);
-  const callee = parseWorkflowDocument(calleeText);
-  const job = caller.callJobs.find((entry) => entry.id === jobId);
-  const failures = [];
-  if (!job)
-    failures.push({
-      code: "call-job-missing",
-      message: `reusable-workflow call job is missing: ${jobId}`,
-    });
-  if (!callee.interface.reusable)
-    failures.push({
-      code: "callee-not-reusable",
-      message: "callee does not declare on.workflow_call",
-    });
-
-  failures.push(
-    ...validateCoordinate(job, {
-      repository: calleeRepository,
-      workflowPath: calleeWorkflowPath,
-      sha: calleeSha,
-    }),
-  );
-  if (!exactSha(calleeSha))
-    failures.push({
-      code: "callee-sha-invalid",
-      message: "callee SHA must be an exact 40-character commit",
-    });
-  if (!exactSha(callerSha) || !exactSha(callerTree))
-    failures.push({
-      code: "caller-source-invalid",
-      message: "caller SHA and tree must be exact 40-character Git object ids",
-    });
-
-  if (job && callee.interface.reusable) {
-    failures.push(...validateInputs(job, callee.interface));
-    failures.push(...validateSecrets(job, callee.interface));
-    failures.push(
-      ...validatePermissions(job.permissions, callee.interface.permissions),
-    );
-  }
-  failures.push(...validateEvents(caller.triggers, trustedEventClasses));
-
-  const contract = {
-    schema: WORKFLOW_CALL_CONTRACT,
-    caller: {
-      repository: callerRepository,
-      workflowPath: callerWorkflowPath,
-      workflowDigest: sha256(String(callerText || "")),
-      jobId,
-      eventClasses: caller.triggers,
-      uses: job?.uses || "",
-      inputs: job?.with || {},
-      secretNames:
-        job?.secrets === "inherit"
-          ? ["*"]
-          : Object.keys(job?.secrets || {}).sort(),
-      permissions: job?.permissions || {},
-    },
-    callee: {
-      repository: calleeRepository,
-      workflowPath: calleeWorkflowPath,
-      sha: String(calleeSha || "").toLowerCase(),
-      workflowDigest: sha256(String(calleeText || "")),
-      interface: interfaceProjection(callee.interface),
-    },
-    trustedEventClasses: [...new Set(trustedEventClasses)].sort(),
-  };
-  const contractRoot = sha256(stableJson(contract));
-  if (expectedContractRoot && expectedContractRoot !== contractRoot) {
-    failures.push({
-      code: "contract-root-mismatch",
-      message: `workflow call contract root ${contractRoot} does not match accepted ${expectedContractRoot}`,
-    });
-  }
-  const receipt = {
-    schema: WORKFLOW_CALL_RECEIPT,
-    contractRoot,
-    caller: {
-      repository: callerRepository,
-      sha: String(callerSha || "").toLowerCase(),
-      tree: String(callerTree || "").toLowerCase(),
-      sourceState: callerSourceState,
-      workflowPath: callerWorkflowPath,
-      workflowDigest: contract.caller.workflowDigest,
-    },
-    callee: {
-      repository: calleeRepository,
-      sha: String(calleeSha || "").toLowerCase(),
-      workflowPath: calleeWorkflowPath,
-      workflowDigest: contract.callee.workflowDigest,
-    },
-    eventClasses: caller.triggers,
-  };
-  return {
-    schema: "kungfu-buildchain-workflow-call-check/v1",
-    ok: failures.length === 0,
-    status: failures.length === 0 ? "passed" : "failed",
-    failures,
-    contract,
-    contractRoot,
-    receipt,
-    receiptRoot: sha256(stableJson(receipt)),
-    receiptReusable: failures.length === 0 && callerSourceState === "clean",
-  };
-}
-
-export function assertWorkflowCallContract(options) {
-  const report = evaluateWorkflowCallContract(options);
-  if (!report.ok) {
-    throw new Error(
-      `Reusable workflow call contract failed:\n${report.failures.map((entry) => `${entry.code}: ${entry.message}`).join("\n")}`,
-    );
-  }
-  return report;
-}