@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/build/demo/schema.js

@@ -0,0 +1,278 @@
+import {
+  DIGEST_PATTERN,
+  invariant,
+  sha256,
+  readRegular,
+  decodeUtf8,
+  readJson,
+  exactKeys,
+  integer,
+  text,
+} from "./io.js";
+
+export const REQUIRED_ADAPTER_FILES = [
+  "complete-transcript.txt",
+  "public-projection.json",
+  "scene.json",
+];
+
+export const OPTIONAL_ADAPTER_FILES = [
+  "terminal-capture.json",
+  "complete-transcript-720p.txt",
+  "public-projection-720p.json",
+  "scene-720p.json",
+  "terminal-capture-720p.json",
+  "rendition-set.json",
+];
+
+export const MAX_TERMINAL_CAPTURE_BYTES = 4 * 1024 * 1024;
+
+export const MAX_TERMINAL_CAPTURE_EVENTS = 10_000;
+
+export const STANDARD_MAX_DURATION_MS = 60_000;
+
+export const LONG_FORM_MAX_DURATION_MS = 180_000;
+
+export const LONG_FORM_MAX_FPS = 10;
+
+export const MAX_RENDER_FRAMES = 1_800;
+
+export function validateScene(value) {
+  exactKeys(
+    value,
+    ["schema", "id", "width", "height", "fps", "durationMs", "title"],
+    [
+      "durationClass",
+      "compositionMode",
+      "commandLabel",
+      "background",
+      "accent",
+    ],
+    "scene",
+  );
+  invariant(
+    value.schema === "build-images.demo-scene/v1",
+    "unsupported scene schema",
+  );
+  invariant(
+    /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value.id),
+    "scene.id is invalid",
+  );
+  integer(value.width, 640, 1920, "scene.width");
+  integer(value.height, 360, 1080, "scene.height");
+  const durationClass = value.durationClass ?? "standard";
+  invariant(
+    durationClass === "standard" || durationClass === "long-form",
+    "scene.durationClass is invalid",
+  );
+  const compositionMode = value.compositionMode ?? "presentation-framed";
+  invariant(
+    compositionMode === "presentation-framed" ||
+      compositionMode === "terminal-fill",
+    "scene.compositionMode is invalid",
+  );
+  const maximumDurationMs =
+    durationClass === "long-form"
+      ? LONG_FORM_MAX_DURATION_MS
+      : STANDARD_MAX_DURATION_MS;
+  const maximumFps = durationClass === "long-form" ? LONG_FORM_MAX_FPS : 30;
+  integer(value.fps, 1, maximumFps, "scene.fps");
+  integer(value.durationMs, 500, maximumDurationMs, "scene.durationMs");
+  invariant(
+    Math.ceil((value.durationMs / 1000) * value.fps) <= MAX_RENDER_FRAMES,
+    "scene exceeds the deterministic source-frame bound",
+  );
+  text(value.title, 1, 120, "scene.title");
+  if (value.commandLabel !== undefined)
+    text(value.commandLabel, 0, 160, "scene.commandLabel");
+  for (const key of ["background", "accent"]) {
+    if (value[key] !== undefined)
+      invariant(
+        /^#[0-9a-fA-F]{6}$/.test(value[key]),
+        `scene.${key} is invalid`,
+      );
+  }
+  return {
+    schema: value.schema,
+    id: value.id,
+    width: value.width,
+    height: value.height,
+    fps: value.fps,
+    ...(value.durationClass === undefined ? {} : { durationClass }),
+    compositionMode,
+    durationMs: value.durationMs,
+    title: value.title,
+    commandLabel: value.commandLabel ?? "",
+    background: (value.background ?? "#10151f").toLowerCase(),
+    accent: (value.accent ?? "#67e8a5").toLowerCase(),
+  };
+}
+
+export function validateProjection(value, scene, transcriptLineCount) {
+  exactKeys(
+    value,
+    ["schema", "evidenceClass", "claimBoundary", "cues"],
+    [],
+    "projection",
+  );
+  invariant(
+    value.schema === "build-images.demo-projection/v1",
+    "unsupported projection schema",
+  );
+  text(value.evidenceClass, 1, 120, "projection.evidenceClass");
+  text(value.claimBoundary, 1, 500, "projection.claimBoundary");
+  invariant(
+    Array.isArray(value.cues) &&
+      value.cues.length > 0 &&
+      value.cues.length <= 240,
+    "projection.cues is invalid",
+  );
+  for (const [index, cue] of value.cues.entries()) {
+    exactKeys(
+      cue,
+      ["startMs", "endMs", "transcriptLines"],
+      ["annotation"],
+      `projection.cues[${index}]`,
+    );
+    integer(
+      cue.startMs,
+      0,
+      scene.durationMs - 1,
+      `projection.cues[${index}].startMs`,
+    );
+    integer(cue.endMs, 1, scene.durationMs, `projection.cues[${index}].endMs`);
+    invariant(
+      cue.endMs > cue.startMs,
+      `projection.cues[${index}] has a non-positive interval`,
+    );
+    invariant(
+      Array.isArray(cue.transcriptLines) &&
+        cue.transcriptLines.length > 0 &&
+        cue.transcriptLines.length <= 80,
+      `projection.cues[${index}].transcriptLines is invalid`,
+    );
+    const lines = new Set();
+    for (const line of cue.transcriptLines) {
+      integer(
+        line,
+        1,
+        transcriptLineCount,
+        `projection.cues[${index}] transcript line`,
+      );
+      invariant(
+        !lines.has(line),
+        `projection.cues[${index}] repeats transcript line ${line}`,
+      );
+      lines.add(line);
+    }
+    if (cue.annotation !== undefined)
+      text(cue.annotation, 0, 200, `projection.cues[${index}].annotation`);
+  }
+  return {
+    schema: value.schema,
+    evidenceClass: value.evidenceClass,
+    claimBoundary: value.claimBoundary,
+    cues: value.cues.map((cue) => ({
+      startMs: cue.startMs,
+      endMs: cue.endMs,
+      transcriptLines: cue.transcriptLines,
+      annotation: cue.annotation ?? "",
+    })),
+  };
+}
+
+export const RENDITION_VALIDATION_HELPERS = {
+  decodeBase64,
+  decodeUtf8,
+  digestPattern: DIGEST_PATTERN,
+  exactKeys,
+  integer,
+  invariant,
+  maxBytes: MAX_TERMINAL_CAPTURE_BYTES,
+  maxEvents: MAX_TERMINAL_CAPTURE_EVENTS,
+  readJson,
+  readRegular,
+  sha256,
+  text,
+  validateProjection,
+  validateScene,
+};
+
+export function validateSourceCoordinate(value) {
+  exactKeys(
+    value,
+    [
+      "schema",
+      "repository",
+      "runId",
+      "runAttempt",
+      "sourceSha",
+      "id",
+      "nodeId",
+      "name",
+      "digest",
+      "sizeInBytes",
+      "createdAt",
+      "expiresAt",
+    ],
+    [],
+    "sourceArtifact",
+  );
+  invariant(
+    value.schema === "buildchain.github-artifact-coordinate/v1",
+    "unsupported source artifact coordinate schema",
+  );
+  invariant(
+    /^[^/\s]+\/[^/\s]+$/.test(value.repository),
+    "sourceArtifact.repository is invalid",
+  );
+  for (const key of ["runId", "runAttempt", "id"]) {
+    invariant(
+      /^[1-9][0-9]*$/.test(value[key]),
+      `sourceArtifact.${key} is invalid`,
+    );
+  }
+  invariant(
+    /^[0-9a-f]{40}$/.test(value.sourceSha),
+    "sourceArtifact.sourceSha is invalid",
+  );
+  text(value.nodeId, 1, 256, "sourceArtifact.nodeId");
+  text(value.name, 1, 256, "sourceArtifact.name");
+  invariant(!/[\0\r\n]/.test(value.name), "sourceArtifact.name is invalid");
+  invariant(
+    DIGEST_PATTERN.test(value.digest),
+    "sourceArtifact.digest is invalid",
+  );
+  integer(
+    value.sizeInBytes,
+    0,
+    Number.MAX_SAFE_INTEGER,
+    "sourceArtifact.sizeInBytes",
+  );
+  const createdAt = Date.parse(value.createdAt);
+  const expiresAt = Date.parse(value.expiresAt);
+  invariant(Number.isFinite(createdAt), "sourceArtifact.createdAt is invalid");
+  invariant(
+    Number.isFinite(expiresAt) && expiresAt > createdAt,
+    "sourceArtifact.expiresAt is invalid",
+  );
+  return value;
+}
+
+export function decodeBase64(value, label) {
+  invariant(
+    typeof value === "string" &&
+      value.length > 0 &&
+      value.length <= MAX_TERMINAL_CAPTURE_BYTES * 2 &&
+      /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        value,
+      ),
+    `${label} must be canonical base64`,
+  );
+  const decoded = Buffer.from(value, "base64");
+  invariant(
+    decoded.toString("base64") === value,
+    `${label} must be canonical base64`,
+  );
+  return decoded;
+}

package/packages/core/build/demo/transport-smoke.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { prepareArtifact, validateScenario } from "./scenario.js";
+
+const NON_AUTHORITIES = [
+  "first-party-identity",
+  "system-identity",
+  "kfd-compliance",
+  "product-system-metadata",
+  "package-metadata",
+  "registry-history",
+  "scan-output",
+  "standalone-generation",
+];
+
+function fail(message) {
+  throw new Error(`auditable demo transport smoke: ${message}`);
+}
+
+function inside(root, relative, label) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative))
+    fail(`${label} must be relative`);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  if (
+    resolved === resolvedRoot ||
+    !resolved.startsWith(`${resolvedRoot}${path.sep}`)
+  )
+    fail(`${label} escapes its root`);
+  return resolved;
+}
+
+function removeExecuteBits(root) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory()) removeExecuteBits(file);
+    else if (entry.isFile())
+      fs.chmodSync(file, fs.statSync(file).mode & ~0o111);
+  }
+}
+
+function isolatedEnvironment(home, declared) {
+  const env = {
+    PATH: "/usr/local/bin:/usr/bin:/bin",
+    HOME: home,
+    XDG_CACHE_HOME: path.join(home, ".cache"),
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+    XDG_DATA_HOME: path.join(home, ".local/share"),
+    XDG_STATE_HOME: path.join(home, ".local/state"),
+    LANG: "C.UTF-8",
+    LC_ALL: "C.UTF-8",
+    TZ: "UTC",
+    CI: "true",
+    TERM: "xterm-256color",
+    COLORTERM: "truecolor",
+    FORCE_COLOR: "3",
+  };
+  for (const [key, value] of Object.entries(declared)) {
+    if (Object.hasOwn(env, key))
+      fail(
+        `scenario environment may not override the isolated baseline: ${key}`,
+      );
+    env[key] = value;
+  }
+  return env;
+}
+
+export function runTransportSmoke({ artifactRoot, scenarioPath }) {
+  if (process.platform === "win32")
+    fail("transport smoke currently requires a POSIX host");
+  const root = path.resolve(artifactRoot);
+  const scenario = validateScenario(
+    JSON.parse(fs.readFileSync(path.resolve(scenarioPath), "utf8")),
+  );
+  if (!scenario.transportSmoke) fail("scenario.transportSmoke is required");
+  const distributionRelative = path.posix.dirname(
+    scenario.artifact.metadataPath,
+  );
+  const sourceDistribution =
+    distributionRelative === "."
+      ? root
+      : inside(root, distributionRelative, "distribution root");
+  const temporaryRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-demo-transport-"),
+  );
+  try {
+    const transportedRoot = path.join(temporaryRoot, "artifact");
+    const transportedDistribution =
+      distributionRelative === "."
+        ? transportedRoot
+        : path.join(transportedRoot, ...distributionRelative.split("/"));
+    fs.mkdirSync(path.dirname(transportedDistribution), { recursive: true });
+    fs.cpSync(sourceDistribution, transportedDistribution, {
+      recursive: true,
+      dereference: false,
+      preserveTimestamps: true,
+      verbatimSymlinks: true,
+    });
+    removeExecuteBits(transportedDistribution);
+    const prepared = prepareArtifact({
+      artifactRoot: transportedRoot,
+      scenarioPath,
+    });
+    const binary = inside(
+      transportedRoot,
+      scenario.artifact.binaryPath,
+      "transport smoke binary",
+    );
+    const workspace = path.join(temporaryRoot, "workspace");
+    const home = path.join(temporaryRoot, "home");
+    fs.mkdirSync(workspace);
+    fs.mkdirSync(home);
+    const smoke = scenario.transportSmoke;
+    const result = spawnSync(binary, smoke.argv, {
+      cwd: workspace,
+      env: isolatedEnvironment(home, scenario.execution.environment),
+      encoding: "utf8",
+      timeout: smoke.timeoutSeconds * 1000,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    const output = `${result.stdout || ""}${result.stderr || ""}`;
+    if (result.error) fail(`could not execute: ${result.error.message}`);
+    if (!smoke.expectedExitCodes.includes(result.status))
+      fail(`exited with ${result.status}; output: ${output.slice(-4096)}`);
+    for (const expected of smoke.stdoutIncludes)
+      if (!output.includes(expected)) fail(`output is missing: ${expected}`);
+    return {
+      schema: "buildchain.declarative-demo-transport-smoke/v1",
+      status: "passed",
+      executableFiles: prepared.executableFiles,
+      argv: smoke.argv,
+      exitCode: result.status,
+      outputRoot: `sha256:${crypto.createHash("sha256").update(output).digest("hex")}`,
+      authority: {
+        classification: "pre-upload-transport-diagnostic",
+        grants: [],
+        nonAuthorities: NON_AUTHORITIES,
+      },
+    };
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}

package/packages/core/build/demo/values.js

@@ -0,0 +1,137 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+export const SAFE_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+export const SAFE_MARKER = /^[a-z0-9][a-z0-9._:-]{0,79}$/u;
+export const NON_AUTHORITIES = [
+  "first-party-identity",
+  "system-identity",
+  "kfd-compliance",
+  "product-system-metadata",
+  "package-metadata",
+  "registry-history",
+  "scan-output",
+  "standalone-generation",
+];
+export const RENDITIONS = [
+  {
+    id: "1080p",
+    role: "primary",
+    columns: 150,
+    rows: 36,
+    width: 1920,
+    height: 1080,
+  },
+  {
+    id: "720p",
+    role: "responsive",
+    columns: 100,
+    rows: 28,
+    width: 1280,
+    height: 720,
+  },
+];
+export const STANDARD_MAX_SECONDS = 60;
+export const LONG_FORM_MAX_SECONDS = 180;
+export const PRESENTATION_FRAMED = "presentation-framed";
+export const TERMINAL_FILL = "terminal-fill";
+export const MAX_EXECUTABLE_FILES = 32;
+export const MAX_METADATA_MEMBER_BYTES = 8 * 1024 * 1024;
+export const MAX_MEDIA_MEMBER_BYTES = 64 * 1024 * 1024;
+export const MAX_GATE_BUNDLE_BYTES = 64 * 1024 * 1024;
+export const MAX_MEDIA_BUNDLE_BYTES = 128 * 1024 * 1024;
+
+export function durationPolicy(value = "standard") {
+  requireValue(
+    value === "standard" || value === "long-form",
+    "scenario duration class is invalid",
+  );
+  return {
+    durationClass: value,
+    maximumSeconds:
+      value === "long-form" ? LONG_FORM_MAX_SECONDS : STANDARD_MAX_SECONDS,
+  };
+}
+
+export function fail(message) {
+  throw new Error(`auditable demo platform: ${message}`);
+}
+
+export function requireValue(condition, message) {
+  if (!condition) fail(message);
+}
+
+export function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+export function stableJson(value) {
+  return `${JSON.stringify(stableValue(value), null, 2)}\n`;
+}
+
+export function rootBytes(value) {
+  return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+
+export function rootJson(value) {
+  return rootBytes(Buffer.from(stableJson(value)));
+}
+
+export function regular(file, label, maximum = 8 * 1024 * 1024) {
+  const metadata = fs.lstatSync(file);
+  requireValue(
+    metadata.isFile() && !metadata.isSymbolicLink() && metadata.size <= maximum,
+    `${label} must be a bounded regular file`,
+  );
+  return fs.readFileSync(file);
+}
+
+export function readJson(file, label) {
+  try {
+    const value = JSON.parse(regular(file, label).toString("utf8"));
+    requireValue(
+      value && typeof value === "object" && !Array.isArray(value),
+      `${label} must contain an object`,
+    );
+    return value;
+  } catch (error) {
+    if (error instanceof SyntaxError) fail(`${label} is invalid JSON`);
+    throw error;
+  }
+}
+
+export function inside(root, relative, label) {
+  requireValue(
+    typeof relative === "string" && relative && !path.isAbsolute(relative),
+    `${label} must be relative`,
+  );
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  requireValue(
+    resolved !== resolvedRoot &&
+      resolved.startsWith(`${resolvedRoot}${path.sep}`),
+    `${label} escapes its root`,
+  );
+  return resolved;
+}
+
+export function exactKeys(value, required, optional, label) {
+  requireValue(
+    value && typeof value === "object" && !Array.isArray(value),
+    `${label} must be an object`,
+  );
+  const allowed = new Set([...required, ...optional]);
+  for (const key of required)
+    requireValue(Object.hasOwn(value, key), `${label}.${key} is required`);
+  for (const key of Object.keys(value))
+    requireValue(allowed.has(key), `${label}.${key} is not allowed`);
+}

package/packages/core/build/environment/action.js

@@ -0,0 +1,17 @@
+import os from "node:os";
+import { readBuildActionContext } from "../plan/action-context.js";
+import { provisionBuildEnvironment } from "./provision.js";
+import { runnerObservation } from "../../providers/runner/observation.js";
+export function provisionBuildEnvironmentAction(core, env) {
+  const context = readBuildActionContext(core, env);
+  const result = provisionBuildEnvironment({
+    ...context,
+    tools: core.getInput("tools") === "true",
+    token: core.getInput("token", { required: true }),
+    environment: env,
+    observation: runnerObservation(env),
+    runnerTemp: env.RUNNER_TEMP || os.tmpdir(),
+    home: os.homedir(),
+  });
+  for (const directory of result.paths) core.addPath(directory);
+}

package/packages/core/build/environment/provision.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { lockedSourceCheckout } from "../../providers/source-checkout/transaction.js";
+import { createRunnerEvidence } from "../../providers/commands/aws-runner-burst-core.mjs";
+import { createWindowsJitEvidence } from "../../providers/commands/aws-windows-jit-core.mjs";
+import { createMacosJitEvidence } from "../../providers/commands/aws-macos-jit-core.mjs";
+import { prepareAwsCodeBuildToolchain } from "../../providers/toolchain/codebuild.js";
+import { writeJson } from "../plan/values.js";
+
+export function provisionBuildEnvironment({
+  plan,
+  platform,
+  workspace,
+  sourceRoot,
+  tools,
+  token,
+  environment,
+  observation,
+  runnerTemp,
+  home,
+}) {
+  const checkout = plan.environment.checkout;
+  const evidence = lockedSourceCheckout({
+    workspace,
+    checkoutPath: sourceRoot,
+    repository: plan.run.repository,
+    sourceSha: plan.source.sha,
+    sourceTreeSha: plan.source.tree_sha,
+    fetchRef: plan.source.ref,
+    historyMode: checkout.history_mode,
+    mode: checkout.mode,
+    mirrorUrlTemplate: checkout.mirror_url_template,
+    referenceRepositoryTemplate: checkout.reference_repository_template,
+    fallback: checkout.fallback,
+    timeoutSeconds: checkout.timeout_seconds,
+    githubTimeoutSeconds: checkout.github_timeout_seconds,
+    fetchAttempts: checkout.fetch_attempts,
+    diagnosticsPath: path.join(
+      sourceRoot,
+      ".buildchain/diagnostics/source-checkout.json",
+    ),
+    githubToken: token,
+    environment,
+  });
+  if (!platform || !tools) return { checkout: evidence, paths: [] };
+  const evidenceRoot = path.join(
+    sourceRoot,
+    `.buildchain/artifacts/${platform.id}`,
+  );
+  const paths = [];
+  const common = {
+    repository: plan.run.repository,
+    sourceSha: plan.source.sha,
+    sourceRef: plan.source.ref,
+    githubRunId: plan.run.id,
+    githubRunAttempt: plan.run.attempt,
+    githubJob: observation.job,
+    runnerName: observation.name,
+    runnerLabels: observation.labels,
+    instanceId: observation.ec2.instanceId,
+    instanceType: observation.ec2.instanceType,
+    amiId: observation.ec2.amiId,
+    amiName: observation.ec2.amiName,
+    availabilityZone: observation.ec2.availabilityZone,
+    runnerStartedAt: observation.ec2.runnerStartedAt,
+    runnerExitedAt: observation.ec2.runnerExitedAt,
+    cacheMode: checkout.mode,
+  };
+  if (platform.provider === "aws-codebuild") {
+    const runner = createRunnerEvidence({
+      provider: platform.provider,
+      project: platform.project,
+      repository: plan.run.repository,
+      sourceSha: plan.source.sha,
+      sourceRef: plan.source.ref,
+      runId: plan.run.id,
+      runAttempt: plan.run.attempt,
+      job: observation.job,
+      codeBuildBuildId: observation.codebuild.buildId,
+      codeBuildBuildArn: observation.codebuild.buildArn,
+      codeBuildInitiator: observation.codebuild.initiator,
+      region: observation.codebuild.region,
+    });
+    writeJson(path.join(evidenceRoot, "aws-runner-burst.json"), runner);
+    const prepared = prepareAwsCodeBuildToolchain({
+      runnerTemp,
+      evidencePath: path.join(evidenceRoot, "aws-native-toolchain.json"),
+      buildId: observation.codebuild.buildId,
+      environment,
+    });
+    paths.push(...prepared.paths);
+  }
+  if (platform.provider === "aws-ec2-windows-jit")
+    writeJson(
+      path.join(evidenceRoot, "aws-windows-jit.json"),
+      createWindowsJitEvidence({
+        ...common,
+        campaignId: observation.ec2.campaignId,
+        launchedAt: observation.ec2.launchedAt,
+        terminatedAt: observation.ec2.terminatedAt,
+        cleanupResult: observation.ec2.cleanupResult,
+      }),
+    );
+  if (platform.provider === "aws-ec2-macos-jit")
+    writeJson(
+      path.join(evidenceRoot, "aws-macos-jit.json"),
+      createMacosJitEvidence({
+        ...common,
+        hostId: observation.ec2.hostId,
+        hostAllocatedAt: observation.ec2.hostAllocatedAt,
+        instanceLaunchedAt: observation.ec2.launchedAt,
+      }),
+    );
+  return {
+    checkout: evidence,
+    paths: [
+      ...paths,
+      path.join(home, ".local/bin"),
+      path.join(home, ".cargo/bin"),
+    ],
+  };
+}