@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/packages/core/oci-publication-bundle.js

@@ -0,0 +1,281 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { domainContentRoot } from "./canonical-contracts.js";
+import {
+  verifyOciGraph,
+  verifyOciDestination,
+} from "./oci-publication-graph.js";
+
+export const OCI_FAMILY_SCHEMA = "kungfu-buildchain-oci-family/v1";
+const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+const namePattern = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+
+export function sealOciPublicationBundle({ bundleRoot, body }) {
+  const manifest = {
+    ...body,
+    root: domainContentRoot("oci-publication-family", body),
+  };
+  verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: body.repository,
+    sourceSha: body.sourceSha,
+    version: body.version,
+  });
+  return manifest;
+}
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(`OCI bundle: ${message}`);
+}
+
+export function ociBundleFile(root, relative) {
+  requireValue(
+    typeof relative === "string" &&
+      relative.length > 0 &&
+      !relative.includes("\\") &&
+      !path.isAbsolute(relative) &&
+      !relative.split(/[\\/]/u).some((p) => p === ".." || p === "." || !p),
+    "unsafe file path",
+  );
+  const base = fs.realpathSync(root);
+  let current = base;
+  for (const segment of relative.split("/")) {
+    current = path.join(current, segment);
+    requireValue(
+      !fs.lstatSync(current).isSymbolicLink(),
+      "symlinks are forbidden",
+    );
+  }
+  requireValue(
+    fs.statSync(current).isFile() &&
+      fs.realpathSync(current).startsWith(`${base}${path.sep}`),
+    "file escapes bundle",
+  );
+  return current;
+}
+
+function fileDigest(file) {
+  const hash = crypto.createHash("sha256"),
+    buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, "r");
+  try {
+    for (;;) {
+      const size = fs.readSync(fd, buffer);
+      if (!size) break;
+      hash.update(buffer.subarray(0, size));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function verifyImageProvenance(image, config, sourceSha, version) {
+  const labels = config.config?.Labels || {};
+  requireValue(
+    image.content &&
+      /^[0-9a-f]{40}$/u.test(image.content.sourceSha) &&
+      typeof image.content.version === "string" &&
+      image.content.version.length > 0,
+    "missing image content provenance",
+  );
+  requireValue(
+    labels["org.opencontainers.image.revision"] === image.content.sourceSha &&
+      labels["org.opencontainers.image.version"] === image.content.version,
+    "image content provenance mismatch",
+  );
+  if (image.action === "built")
+    requireValue(
+      image.content.sourceSha === sourceSha &&
+        image.content.version === version,
+      "built image is not from the candidate source",
+    );
+  if (image.contractMajor !== undefined)
+    requireValue(
+      Number.isInteger(image.contractMajor) &&
+        image.contractMajor > 0 &&
+        labels["io.kungfu.image.contract-major"] ===
+          String(image.contractMajor),
+      "image contract major mismatch",
+    );
+  if (image.parentDigest)
+    requireValue(
+      digestPattern.test(image.parentDigest) &&
+        labels["io.kungfu.image.parent-digest"] === image.parentDigest,
+      "image parent digest mismatch",
+    );
+  if (image.content.materialSha)
+    requireValue(
+      /^[0-9a-f]{40}$/u.test(image.content.materialSha) &&
+        labels["io.kungfu.buildchain.release-material-sha"] ===
+          image.content.materialSha,
+      "image material provenance mismatch",
+    );
+}
+
+export function verifyOciPublicationBundle({
+  bundleRoot,
+  manifest,
+  repository,
+  sourceSha,
+  version,
+}) {
+  requireValue(
+    [OCI_FAMILY_SCHEMA, "kungfu-buildchain-oci-family/v2"].includes(
+      manifest?.schema,
+    ),
+    "unsupported manifest schema",
+  );
+  const { root, ...body } = manifest;
+  const computed = domainContentRoot("oci-publication-family", body);
+  requireValue(root === computed, "manifest root mismatch");
+  requireValue(
+    manifest.repository === repository &&
+      manifest.sourceSha === sourceSha &&
+      manifest.version === version,
+    "candidate identity mismatch",
+  );
+  requireValue(
+    /^[a-z0-9-]+\/[a-z0-9._-]+$/u.test(repository),
+    "invalid repository",
+  );
+  requireValue(
+    Array.isArray(manifest.images) && manifest.images.length > 0,
+    "empty image family",
+  );
+  const expected = manifest.expectedImages;
+  requireValue(
+    Array.isArray(expected) &&
+      expected.length === new Set(expected).size &&
+      expected.every((n) => namePattern.test(n)),
+    "invalid expected image family",
+  );
+  const actual = manifest.images.map((i) => i.name).sort();
+  requireValue(
+    JSON.stringify(actual) === JSON.stringify([...expected].sort()),
+    "incomplete or duplicate image family",
+  );
+  const files = new Map();
+  const graphs = new Map();
+  for (const image of manifest.images) {
+    verifyOciDestination(image, manifest, requireValue);
+    requireValue(
+      digestPattern.test(image.digest) &&
+        ["built", "reused"].includes(image.action),
+      "invalid image identity",
+    );
+    requireValue(
+      /^linux\/(amd64|arm64)$/u.test(image.platform) ||
+        (manifest.schema.endsWith("/v2") &&
+          ["multi-platform", "compose"].includes(image.platform)),
+      "unsupported image platform",
+    );
+    const prefix = image.layout;
+    const descriptorFile = (descriptor) => {
+      requireValue(
+        digestPattern.test(descriptor.digest) &&
+          Number.isSafeInteger(descriptor.size) &&
+          descriptor.size >= 0 &&
+          !descriptor.urls,
+        "invalid OCI descriptor",
+      );
+      const relative = `${prefix}/blobs/sha256/${descriptor.digest.slice(7)}`;
+      const file = ociBundleFile(bundleRoot, relative);
+      requireValue(
+        fs.statSync(file).size === descriptor.size,
+        "OCI blob size mismatch",
+      );
+      if (!files.has(file))
+        requireValue(
+          fileDigest(file) === descriptor.digest,
+          "OCI blob digest mismatch",
+        );
+      if (Object.hasOwn(descriptor, "data")) {
+        requireValue(
+          descriptor.size <= 1024 * 1024 &&
+            descriptor.data === fs.readFileSync(file).toString("base64"),
+          "embedded OCI content mismatch",
+        );
+      }
+      files.set(file, descriptor);
+      return file;
+    };
+    const layout = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/oci-layout`)),
+    );
+    requireValue(
+      layout.imageLayoutVersion === "1.0.0",
+      "unsupported OCI layout",
+    );
+    const index = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/index.json`)),
+    );
+    const selected = (index.manifests || []).filter(
+      (descriptor) =>
+        descriptor.digest === image.digest &&
+        (descriptor.annotations?.["org.opencontainers.image.ref.name"] ===
+          image.name ||
+          index.manifests.length === 1),
+    );
+    requireValue(
+      index.schemaVersion === 2 && selected.length === 1,
+      "OCI index must select one exact image manifest",
+    );
+    if (manifest.schema.endsWith("/v2")) {
+      graphs.set(
+        image.name,
+        verifyOciGraph({
+          image,
+          manifest,
+          descriptor: selected[0],
+          descriptorFile,
+          requireValue,
+          verifyProvenance: (config) =>
+            verifyImageProvenance(image, config, sourceSha, version),
+        }),
+      );
+    } else {
+      const document = JSON.parse(fs.readFileSync(descriptorFile(selected[0])));
+      requireValue(
+        document.schemaVersion === 2 &&
+          [
+            "application/vnd.oci.image.manifest.v1+json",
+            "application/vnd.docker.distribution.manifest.v2+json",
+          ].includes(document.mediaType) &&
+          Array.isArray(document.layers),
+        "unsupported OCI image manifest",
+      );
+      const config = JSON.parse(
+        fs.readFileSync(descriptorFile(document.config)),
+      );
+      requireValue(
+        `${config.os}/${config.architecture}` === image.platform,
+        "OCI platform mismatch",
+      );
+      verifyImageProvenance(image, config, sourceSha, version);
+      for (const layer of document.layers) descriptorFile(layer);
+      graphs.set(image.name, {
+        manifests: [selected[0]],
+        blobs: [document.config, ...document.layers],
+      });
+    }
+    const smokeFile = ociBundleFile(bundleRoot, image.smoke.path);
+    requireValue(
+      fileDigest(smokeFile) === image.smoke.sha256,
+      "smoke evidence digest mismatch",
+    );
+    const smoke = JSON.parse(fs.readFileSync(smokeFile));
+    requireValue(
+      smoke.passed === true && smoke.image === image.name,
+      "smoke qualification failed",
+    );
+  }
+  return {
+    root: computed,
+    manifest,
+    graphs,
+    bundleRoot: fs.realpathSync(bundleRoot),
+  };
+}

package/packages/core/oci-publication-graph.js

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+
+const imageTypes = [
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+];
+const indexTypes = [
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+];
+const composeType = "application/vnd.docker.compose.project";
+
+export function ociPublicationTag(image, version) {
+  return `${image.kind === "compose" ? "compose-" : ""}v${version}`;
+}
+
+export function verifyOciDestination(image, manifest, requireValue) {
+  const compose = manifest.schema.endsWith("/v2") && image.kind === "compose";
+  requireValue(
+    manifest.schema.endsWith("/v2") || !image.kind,
+    "artifact kinds require family v2",
+  );
+  const target =
+    compose &&
+    manifest.images.find(
+      (entry) => entry.name === image.targetImage && entry.kind !== "compose",
+    );
+  requireValue(
+    !image.kind || ["image", "compose"].includes(image.kind),
+    "unsupported artifact kind",
+  );
+  requireValue(!compose || target, "Compose target image is absent");
+  requireValue(
+    image.repository ===
+      `ghcr.io/${manifest.repository}/${compose ? target.name : image.name}`,
+    "destination must belong to the consumer repository",
+  );
+  requireValue(
+    manifest.images.filter(
+      (entry) =>
+        entry.repository === image.repository &&
+        ociPublicationTag(entry, manifest.version) ===
+          ociPublicationTag(image, manifest.version),
+    ).length === 1,
+    "duplicate publication destination",
+  );
+}
+
+export function verifyOciGraph({
+  image,
+  manifest,
+  descriptor,
+  descriptorFile,
+  requireValue: check,
+  verifyProvenance,
+}) {
+  const manifests = [],
+    blobs = new Map(),
+    platforms = [],
+    attestations = [];
+  const visited = new Set();
+  const read = (entry) => JSON.parse(fs.readFileSync(descriptorFile(entry)));
+  function blob(entry) {
+    descriptorFile(entry);
+    blobs.set(entry.digest, entry);
+  }
+  function visit(entry, depth = 0) {
+    check(
+      depth < 4 && visited.size < 256 && !visited.has(entry.digest),
+      "duplicate or excessive OCI graph",
+    );
+    visited.add(entry.digest);
+    const document = read(entry);
+    check(
+      document.schemaVersion === 2 && document.mediaType === entry.mediaType,
+      "OCI descriptor media type mismatch",
+    );
+    if (indexTypes.includes(document.mediaType)) {
+      check(
+        image.kind !== "compose" &&
+          Array.isArray(document.manifests) &&
+          document.manifests.length > 0,
+        "invalid OCI index",
+      );
+      for (const child of document.manifests) visit(child, depth + 1);
+    } else {
+      check(
+        imageTypes.includes(document.mediaType) &&
+          Array.isArray(document.layers),
+        "unsupported OCI manifest",
+      );
+      const config = read(document.config);
+      blob(document.config);
+      for (const layer of document.layers) blob(layer);
+      if (image.kind === "compose") {
+        verifyCompose(document, image, manifest, read, check);
+      } else if (
+        entry.annotations?.["vnd.docker.reference.type"] ===
+        "attestation-manifest"
+      ) {
+        check(
+          entry.platform?.os === "unknown" &&
+            entry.platform?.architecture === "unknown" &&
+            document.layers.length > 0 &&
+            document.layers.every(
+              (layer) => layer.mediaType === "application/vnd.in-toto+json",
+            ),
+          "invalid image attestation",
+        );
+        attestations.push({
+          target: entry.annotations["vnd.docker.reference.digest"],
+          statements: document.layers.map(read),
+        });
+      } else {
+        const platform = `${config.os}/${config.architecture}`;
+        check(
+          /^linux\/(amd64|arm64)$/u.test(platform) &&
+            (!entry.platform ||
+              platform ===
+                `${entry.platform.os}/${entry.platform.architecture}`),
+          "OCI platform mismatch",
+        );
+        check(
+          !platforms.some((found) => found.platform === platform),
+          "duplicate image platform",
+        );
+        platforms.push({ platform, digest: entry.digest });
+        verifyProvenance(config);
+      }
+    }
+    manifests.push(entry);
+  }
+  visit(descriptor);
+  if (image.kind !== "compose") {
+    const expected =
+      image.platform === "multi-platform" ? image.platforms : [image.platform];
+    check(
+      Array.isArray(expected) &&
+        expected.length > 0 &&
+        new Set(expected).size === expected.length &&
+        JSON.stringify([...expected].sort()) ===
+          JSON.stringify(platforms.map((entry) => entry.platform).sort()),
+      "incomplete image platform family",
+    );
+    for (const attestation of attestations) {
+      check(
+        platforms.some((entry) => entry.digest === attestation.target) &&
+          attestation.statements.every((statement) =>
+            statement.subject?.some(
+              (subject) =>
+                `sha256:${subject.digest?.sha256}` === attestation.target,
+            ),
+          ),
+        "image attestation subject mismatch",
+      );
+    }
+  }
+  return { manifests, blobs: [...blobs.values()], platforms };
+}
+
+function verifyCompose(document, image, manifest, read, check) {
+  if (image.preview)
+    check(
+      image.preview.alias === "compose-preview" &&
+        /^\.github\/workflows\/[a-z0-9-]+\.yml$/u.test(
+          image.preview.qualificationWorkflow,
+        ) &&
+        /^(none|sha256:[0-9a-f]{64})$/u.test(image.preview.previousDigest),
+      "invalid Compose preview policy",
+    );
+  check(
+    image.platform === "compose" &&
+      document.artifactType === composeType &&
+      document.config.mediaType === "application/vnd.oci.empty.v1+json" &&
+      document.layers.length === 1 &&
+      document.layers[0].mediaType ===
+        "application/vnd.docker.compose.file+yaml",
+    "unsupported Compose artifact",
+  );
+  // JSON is a YAML subset; this bounded public form needs no executable YAML loader.
+  const project = read(document.layers[0]);
+  check(
+    project.services && Object.keys(project.services).length > 0,
+    "empty Compose application",
+  );
+  const target = manifest.images.find(
+    (entry) => entry.name === image.targetImage,
+  );
+  const references = Object.values(project.services).map(
+    (service) => service.image,
+  );
+  check(
+    references.every(
+      (ref) =>
+        typeof ref === "string" &&
+        /^[a-z0-9./:_-]+@sha256:[0-9a-f]{64}$/u.test(ref),
+    ) && references.includes(`${target.repository}@${target.digest}`),
+    "Compose images must bind exact digests",
+  );
+  check(
+    image.content?.sourceSha === manifest.sourceSha &&
+      image.content?.version === manifest.version &&
+      image.action === "built",
+    "Compose candidate provenance mismatch",
+  );
+}

package/packages/core/paper-agent-entry.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { paperRuntimeSourceMatches } from "./paper-runtime-channels.js";
 
 import {
   PAPER_PATHS,
@@ -12,7 +13,13 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
-import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
+import {
+  mergeNextDevelopmentAgentInstructions,
+  NEXT_DEVELOPMENT_AGENT_SECTION_START,
+  NEXT_DEVELOPMENT_AGENT_SECTION_END,
+  NEXT_DEVELOPMENT_LOCAL_COMMAND,
+} from "./next-development-projection.js";
+import { NEXT_DEVELOPMENT_ADR } from "./next-development-transition.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -148,6 +155,24 @@ export function createPaperAgentEntry({
   };
 }
 
+function mergePaperNextDevelopmentInstructions(current) {
+  const merged = mergeNextDevelopmentAgentInstructions(current);
+  const start = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_START);
+  const end = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_END);
+  const section = merged.slice(start, end)
+    .replace(
+      `\`${NEXT_DEVELOPMENT_ADR}\``,
+      `[Buildchain next-development ADR](https://github.com/kungfu-systems/buildchain/blob/v4/${NEXT_DEVELOPMENT_ADR})`,
+    )
+    .replace(
+      NEXT_DEVELOPMENT_LOCAL_COMMAND,
+      NEXT_DEVELOPMENT_LOCAL_COMMAND.replace(
+        "node scripts/", "node node_modules/@kungfu-tech/buildchain/scripts/",
+      ),
+    );
+  return `${merged.slice(0, start)}${section}${merged.slice(end)}`;
+}
+
 export function paperAgentEntryFiles({
   cwd,
   buildchainVersion,
@@ -168,7 +193,7 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergeNextDevelopmentAgentInstructions(
+      mergePaperNextDevelopmentInstructions(
         mergePaperAgentEntryInstructions(currentAgents, {
           developmentRef: resolvedDevelopmentRef,
         }),
@@ -256,6 +281,7 @@ export function collectPaperAgentEntry({
   buildchainSha = "",
   mode = "contract",
   env = process.env,
+  runtimeAdmission,
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const developmentRef = paperDevelopmentRef(resolvedCwd);
@@ -311,8 +337,8 @@ export function collectPaperAgentEntry({
     workCheck(
       "agent-entry.runtime-source",
       GIT_SHA_PATTERN.test(effectiveBuildchainSha) &&
-        entry.runtime?.sourceSha === effectiveBuildchainSha,
-      "The agent-entry contract is bound to the exact executing Buildchain source SHA.",
+        paperRuntimeSourceMatches(entry.runtime, effectiveBuildchainSha, mode, runtimeAdmission),
+      "The executing Buildchain source is pinned locally or admitted by its v4 channel contract in CI.",
       "buildchain paper migrate --write --json",
     ),
     workCheck(

package/packages/core/paper-fleet.js

@@ -128,7 +128,7 @@ function paperFleetEntry({
     workCheck(
       "managed-surfaces.current",
       !expected.error && managed.every((entry) => entry.status === "current"),
-      "Every Buildchain-owned paper control surface matches v3.",
+      "Every Buildchain-owned paper control surface matches the selected runtime.",
       "buildchain paper migrate --write --json",
     ),
     workCheck(