@kungfu-tech/buildchain 3.0.5-alpha.8 → 3.0.6-alpha.0

package/scripts/artifact-signing-controller.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  RECEIPT_CONTRACT,
+  artifactSigningControlRequestOutputs,
+  assertArtifactSigningControlRequestContext,
+  digestDocument,
+  normalizeControllerStatus,
+  readArtifactSigningControlRequest,
+  required,
+  sealArtifactSigningControlRequest,
+  validateArtifactSigningControlRequest,
+  validateArtifactSigningControllerReceipt,
+} from "./artifact-signing-controller-core.mjs";
+import {
+  assertArtifactSigningDelegationContext,
+  artifactSigningDelegationOutputs,
+  createArtifactSigningDelegation,
+  readArtifactSigningDelegation,
+} from "./artifact-signing-delegation.mjs";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+export {
+  artifactSigningCorrelation,
+  artifactSigningRequestRoot,
+  artifactSigningControlRequestOutputs,
+  assertArtifactSigningControlRequestContext,
+  createArtifactSigningControlRequest,
+  readArtifactSigningControlRequest,
+  sealArtifactSigningControlRequest,
+  validateArtifactSigningControlRequest,
+  validateArtifactSigningControllerReceipt,
+} from "./artifact-signing-controller-core.mjs";
+
+function authorityRuntimeShaFromEnvironment() {
+  return process.env.BUILDCHAIN_AUTHORITY_RUNTIME_SHA || "";
+}
+
+export function settleArtifactSigningControl({
+  request,
+  authorityStatus = process.env.BUILDCHAIN_AUTHORITY_STATUS || "failed",
+  authorityRunId = process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  authorityRuntimeSha = authorityRuntimeShaFromEnvironment(),
+  authorityRunUrl = process.env.BUILDCHAIN_AUTHORITY_RUN_URL || "",
+  authorityResultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT ||
+    "",
+  authorityCorrelationId = process.env.BUILDCHAIN_AUTHORITY_CORRELATION_ID ||
+    "",
+  authorityConclusion = process.env.BUILDCHAIN_AUTHORITY_CONCLUSION || "",
+  controllerRepository = process.env.GITHUB_REPOSITORY,
+  controllerRunId = process.env.GITHUB_RUN_ID,
+  controllerRunAttempt = process.env.GITHUB_RUN_ATTEMPT || "1",
+  controllerJob = process.env.GITHUB_JOB || "artifact-signing-control",
+  controllerRunnerOs = process.env.RUNNER_OS || "Linux",
+  controllerStartedAt = process.env.BUILDCHAIN_CONTROLLER_STARTED_AT ||
+    new Date().toISOString(),
+  controllerCompletedAt = process.env.BUILDCHAIN_CONTROLLER_COMPLETED_AT ||
+    new Date().toISOString(),
+  receiptPath = process.env.BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_PATH,
+  delegationPath = process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+} = {}) {
+  const control = validateArtifactSigningControlRequest(request);
+  const status = normalizeControllerStatus(authorityStatus);
+  const expectedStatus = control.request.count === 0 ? "skipped" : "succeeded";
+  const qualifying =
+    status === expectedStatus &&
+    (control.request.count === 0 || authorityConclusion === "success");
+  if (
+    authorityCorrelationId &&
+    authorityCorrelationId !== control.authority.correlationId
+  ) {
+    throw new Error("authority correlation does not match control request");
+  }
+  if (
+    authorityResultArtifact &&
+    authorityResultArtifact !== control.authority.resultArtifact
+  ) {
+    throw new Error("authority result artifact does not match control request");
+  }
+  const receipt = {
+    schemaVersion: 1,
+    contract: RECEIPT_CONTRACT,
+    requestDigest: control.digest,
+    source: control.source,
+    runtime: {
+      repository: control.runtime.repository,
+      sha: control.runtime.sha,
+    },
+    platform: control.platform,
+    request: control.request,
+    authority: {
+      repository: control.authority.repository,
+      runtimeSha: authorityRuntimeSha,
+      runId: control.request.count > 0 ? authorityRunId : "",
+      runUrl: control.request.count > 0 ? authorityRunUrl : "",
+      resultArtifact: control.request.count > 0 ? authorityResultArtifact : "",
+      correlationId: control.authority.correlationId,
+      conclusion:
+        control.request.count > 0
+          ? authorityConclusion || status
+          : "not-required",
+    },
+    controller: {
+      repository: controllerRepository,
+      runId: controllerRunId,
+      runAttempt: Number(controllerRunAttempt),
+      job: controllerJob,
+      runnerOs: controllerRunnerOs,
+      startedAt: controllerStartedAt,
+      completedAt: controllerCompletedAt,
+      status,
+    },
+    qualifying,
+  };
+  receipt.digest = digestDocument(receipt);
+  const validatedReceipt = validateArtifactSigningControllerReceipt(receipt);
+  const resolvedReceiptPath = path.resolve(
+    required(receiptPath, "controller receipt path"),
+  );
+  fs.mkdirSync(path.dirname(resolvedReceiptPath), { recursive: true });
+  fs.writeFileSync(
+    resolvedReceiptPath,
+    `${JSON.stringify(validatedReceipt, null, 2)}\n`,
+  );
+
+  let delegation = null;
+  if (validatedReceipt.qualifying) {
+    delegation = createArtifactSigningDelegation({
+      sourceRepository: control.source.repository,
+      sourceRunId: control.source.runId,
+      sourceRunAttempt: control.source.runAttempt,
+      sourceSha: control.source.sha,
+      sourceTreeSha: control.source.treeSha,
+      runtimeRepository: control.runtime.repository,
+      runtimeSha: control.runtime.sha,
+      platformId: control.platform.id,
+      platformName: control.platform.name,
+      requestCount: control.request.count,
+      requestArtifact: control.request.artifact,
+      requestRoot: control.request.root,
+      authorityRunId: validatedReceipt.authority.runId,
+      authorityRuntimeSha: validatedReceipt.authority.runtimeSha,
+      resultArtifact: validatedReceipt.authority.resultArtifact,
+      artifactName: control.artifact.name,
+      manifestArtifact: control.artifact.manifestArtifact,
+      diagnosticsArtifact: control.artifact.diagnosticsArtifact,
+      workingDirectory: control.workingDirectory,
+      controllerMode: "detached",
+      controllerReceiptDigest: validatedReceipt.digest,
+    });
+    const resolvedDelegationPath = path.resolve(
+      required(delegationPath, "delegation path"),
+    );
+    fs.mkdirSync(path.dirname(resolvedDelegationPath), { recursive: true });
+    fs.writeFileSync(
+      resolvedDelegationPath,
+      `${JSON.stringify(delegation, null, 2)}\n`,
+    );
+  }
+  return { receipt: validatedReceipt, delegation };
+}
+
+export function readArtifactSigningControllerReceipt(
+  inputPath = process.env.BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_PATH,
+) {
+  const target = path.resolve(required(inputPath, "controller receipt path"));
+  return validateArtifactSigningControllerReceipt(
+    JSON.parse(fs.readFileSync(target, "utf8")),
+  );
+}
+
+export function assertArtifactSigningControllerReceipt({
+  request,
+  receipt,
+  delegation,
+}) {
+  const control = validateArtifactSigningControlRequest(request);
+  const result = validateArtifactSigningControllerReceipt(receipt);
+  const finalDelegation = assertArtifactSigningDelegationContext(delegation, {
+    sourceRepository: control.source.repository,
+    sourceRunId: control.source.runId,
+    sourceRunAttempt: control.source.runAttempt,
+    sourceSha: control.source.sha,
+    runtimeRepository: control.runtime.repository,
+    runtimeSha: control.runtime.sha,
+    platformId: control.platform.id,
+  });
+  const comparisons = [
+    [result.requestDigest, control.digest, "control request digest"],
+    [result.source.treeSha, control.source.treeSha, "source tree SHA"],
+    [result.request.root, control.request.root, "request root"],
+    [result.request.artifact, control.request.artifact, "request artifact"],
+    [
+      result.authority.correlationId,
+      control.authority.correlationId,
+      "correlation",
+    ],
+    [
+      result.authority.runId,
+      finalDelegation.authority.runId,
+      "authority run ID",
+    ],
+    [
+      result.authority.runtimeSha,
+      finalDelegation.authority.runtimeSha,
+      "authority runtime SHA",
+    ],
+    [
+      result.authority.resultArtifact,
+      finalDelegation.authority.resultArtifact,
+      "authority result artifact",
+    ],
+    [
+      finalDelegation.controller.receiptDigest,
+      result.digest,
+      "controller receipt digest",
+    ],
+    [
+      finalDelegation.request.root,
+      result.request.root,
+      "delegation request root",
+    ],
+  ];
+  for (const [actual, expected, label] of comparisons) {
+    if (actual !== expected) {
+      throw new Error(`artifact signing controller ${label} mismatch`);
+    }
+  }
+  if (!result.qualifying) {
+    throw new Error("artifact signing controller receipt is not qualifying");
+  }
+  return { request: control, receipt: result, delegation: finalDelegation };
+}
+
+function expectedContext() {
+  return {
+    sourceRepository: process.env.BUILDCHAIN_EXPECTED_SOURCE_REPOSITORY || "",
+    sourceRunId: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ID || "",
+    sourceRunAttempt: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ATTEMPT || "",
+    sourceSha: process.env.BUILDCHAIN_EXPECTED_SOURCE_SHA || "",
+    sourceTreeSha: process.env.BUILDCHAIN_EXPECTED_SOURCE_TREE_SHA || "",
+    runtimeRepository: process.env.BUILDCHAIN_EXPECTED_RUNTIME_REPOSITORY || "",
+    runtimeSha: process.env.BUILDCHAIN_EXPECTED_RUNTIME_SHA || "",
+    platformId: process.env.BUILDCHAIN_EXPECTED_PLATFORM_ID || "",
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const mode = process.argv[2] || "seal";
+    if (mode === "seal") {
+      sealArtifactSigningControlRequest();
+    } else if (mode === "outputs") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(),
+        expectedContext(),
+      );
+      writeGitHubOutputs(artifactSigningControlRequestOutputs(request));
+    } else if (mode === "settle") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(),
+        expectedContext(),
+      );
+      const { receipt, delegation } = settleArtifactSigningControl({ request });
+      writeGitHubOutputs({
+        "controller-status": receipt.controller.status,
+        "controller-receipt-digest": receipt.digest,
+        "controller-qualifying": String(receipt.qualifying),
+        "delegation-created": String(Boolean(delegation)),
+      });
+    } else if (mode === "verify") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(),
+        expectedContext(),
+      );
+      const checked = assertArtifactSigningControllerReceipt({
+        request,
+        receipt: readArtifactSigningControllerReceipt(),
+        delegation: readArtifactSigningDelegation(),
+      });
+      writeGitHubOutputs({
+        ...artifactSigningDelegationOutputs(checked.delegation),
+        "request-root": checked.receipt.request.root,
+        "controller-receipt-digest": checked.receipt.digest,
+        "controller-status": checked.receipt.controller.status,
+      });
+    } else {
+      throw new Error(`unsupported artifact signing controller mode: ${mode}`);
+    }
+  } catch (error) {
+    console.error(
+      `::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/artifact-signing-delegation.mjs

@@ -22,6 +22,14 @@ function optional(value, label) {
   return normalized;
 }
 
+function sha256Root(value, label) {
+  const normalized = optional(value, label);
+  if (normalized && !/^sha256:[0-9a-f]{64}$/u.test(normalized)) {
+    throw new Error(`${label} must be a canonical sha256 root`);
+  }
+  return normalized;
+}
+
 function exactSha(value, label) {
   const normalized = required(value, label);
   if (!/^[0-9a-f]{40}$/u.test(normalized))
@@ -97,8 +105,13 @@ export function validateArtifactSigningDelegation(value) {
         requestCount > 0
           ? required(value.request?.artifact, "request.artifact")
           : optional(value.request?.artifact, "request.artifact"),
+      root: sha256Root(value.request?.root, "request.root"),
     },
     authority: {
+      runtimeSha:
+        requestCount > 0
+          ? exactSha(value.authority?.runtimeSha, "authority.runtimeSha")
+          : optional(value.authority?.runtimeSha, "authority.runtimeSha"),
       runId:
         requestCount > 0
           ? required(value.authority?.runId, "authority.runId")
@@ -129,15 +142,32 @@ export function validateArtifactSigningDelegation(value) {
       value.workingDirectory || ".",
       "workingDirectory",
     ),
+    controller: {
+      mode: optional(value.controller?.mode, "controller.mode"),
+      receiptDigest: sha256Root(
+        value.controller?.receiptDigest,
+        "controller.receiptDigest",
+      ),
+    },
   };
   if (
     requestCount === 0 &&
-    (delegation.authority.runId || delegation.authority.resultArtifact)
+    (delegation.authority.runtimeSha ||
+      delegation.authority.runId ||
+      delegation.authority.resultArtifact)
   ) {
     throw new Error(
       "unsigned delegation must not contain authority result coordinates",
     );
   }
+  if (
+    Boolean(delegation.controller.mode) !==
+    Boolean(delegation.controller.receiptDigest)
+  ) {
+    throw new Error(
+      "delegation controller mode and receipt digest must be provided together",
+    );
+  }
   return delegation;
 }
 
@@ -153,12 +183,17 @@ export function createArtifactSigningDelegation({
   platformName = process.env.BUILDCHAIN_PLATFORM_NAME,
   requestCount = process.env.BUILDCHAIN_SIGNING_REQUEST_COUNT || "0",
   requestArtifact = process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT || "",
+  requestRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT_DIGEST || "",
   authorityRunId = process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  authorityRuntimeSha = process.env.BUILDCHAIN_AUTHORITY_RUNTIME_SHA || "",
   resultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT || "",
   artifactName = process.env.BUILDCHAIN_ARTIFACT_NAME,
   manifestArtifact = process.env.BUILDCHAIN_MANIFEST_ARTIFACT_NAME,
   diagnosticsArtifact = process.env.BUILDCHAIN_DIAGNOSTICS_ARTIFACT_NAME,
   workingDirectory = process.env.BUILDCHAIN_SIGNING_CWD || ".",
+  controllerMode = process.env.BUILDCHAIN_SIGNING_CONTROLLER_MODE || "",
+  controllerReceiptDigest = process.env
+    .BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_DIGEST || "",
 } = {}) {
   return validateArtifactSigningDelegation({
     schemaVersion: 1,
@@ -172,10 +207,22 @@ export function createArtifactSigningDelegation({
     },
     runtime: { repository: runtimeRepository, sha: runtimeSha },
     platform: { id: platformId, name: platformName },
-    request: { count: Number(requestCount), artifact: requestArtifact },
-    authority: { runId: authorityRunId, resultArtifact },
+    request: {
+      count: Number(requestCount),
+      artifact: requestArtifact,
+      root: requestRoot,
+    },
+    authority: {
+      runtimeSha: authorityRuntimeSha,
+      runId: authorityRunId,
+      resultArtifact,
+    },
     artifact: { name: artifactName, manifestArtifact, diagnosticsArtifact },
     workingDirectory,
+    controller: {
+      mode: controllerMode,
+      receiptDigest: controllerReceiptDigest,
+    },
   });
 }
 
@@ -205,6 +252,7 @@ export function artifactSigningDelegationOutputs(delegation) {
     "request-count": String(value.request.count),
     "request-artifact": value.request.artifact,
     "authority-run-id": value.authority.runId,
+    "authority-runtime-sha": value.authority.runtimeSha,
     "result-artifact": value.authority.resultArtifact,
     "artifact-name": value.artifact.name,
     "manifest-artifact-name": value.artifact.manifestArtifact,

package/scripts/auditable-demo-platform.mjs

@@ -25,6 +25,7 @@ const RENDITIONS = [
 ];
 const STANDARD_MAX_SECONDS = 60;
 const LONG_FORM_MAX_SECONDS = 180;
+const MAX_EXECUTABLE_FILES = 32;
 
 function durationPolicy(value = "standard") {
   requireValue(value === "standard" || value === "long-form", "scenario duration class is invalid");
@@ -143,6 +144,54 @@ function validateArtifact(artifact) {
   requireValue(Array.isArray(artifact.runtimeDependencies) && artifact.runtimeDependencies.length === 0, "scenario artifact must be standalone");
 }
 
+function validateTransportSmoke(smoke) {
+  exactKeys(smoke, ["argv", "timeoutSeconds", "expectedExitCodes", "stdoutIncludes"], [], "scenario.transportSmoke");
+  requireValue(Array.isArray(smoke.argv) && smoke.argv.length >= 1 && smoke.argv.length <= 64 && smoke.argv.every((item) => typeof item === "string" && !item.includes("\0") && item.length <= 512), "scenario transport smoke argv is invalid");
+  requireValue(Number.isInteger(smoke.timeoutSeconds) && smoke.timeoutSeconds >= 1 && smoke.timeoutSeconds <= STANDARD_MAX_SECONDS, "scenario transport smoke timeout is invalid");
+  requireValue(Array.isArray(smoke.expectedExitCodes) && smoke.expectedExitCodes.length >= 1 && smoke.expectedExitCodes.length <= 4 && smoke.expectedExitCodes.every((item) => Number.isInteger(item) && item >= 0 && item <= 255), "scenario transport smoke expected exits are invalid");
+  requireValue(Array.isArray(smoke.stdoutIncludes) && smoke.stdoutIncludes.length <= 32 && smoke.stdoutIncludes.every((item) => typeof item === "string" && item.length >= 1 && item.length <= 256), "scenario transport smoke stdout assertions are invalid");
+}
+
+function validateExecutableClosure({ artifactRoot, scenario, requireExecutable }) {
+  const root = path.resolve(artifactRoot);
+  const artifact = scenario.artifact;
+  const metadata = readJson(inside(root, artifact.metadataPath, "artifact metadata path"), "binary metadata");
+  requireValue(metadata.contract === artifact.metadataContract, "binary metadata contract mismatch");
+  requireValue((metadata.platformId || metadata.platform) === artifact.platformId, "binary metadata platform mismatch");
+  requireValue(JSON.stringify(metadata.runtimeDependencies) === JSON.stringify(artifact.runtimeDependencies), "binary metadata runtime dependency mismatch");
+  requireValue(Array.isArray(metadata.executableFiles) && metadata.executableFiles.length >= 1 && metadata.executableFiles.length <= MAX_EXECUTABLE_FILES, "binary metadata executableFiles must be a bounded non-empty array");
+  const declared = new Set();
+  const files = metadata.executableFiles.map((entry, index) => {
+    const label = `binary metadata executableFiles[${index}]`;
+    exactKeys(entry, ["path", "sha256"], [], label);
+    requireValue(!declared.has(entry.path), `${label}.path is repeated`);
+    declared.add(entry.path);
+    requireValue(/^[0-9a-f]{64}$/u.test(entry.sha256), `${label}.sha256 is invalid`);
+    const file = inside(root, entry.path, `${label}.path`);
+    const bytes = regular(file, label, 256 * 1024 * 1024);
+    requireValue(rootBytes(bytes) === `sha256:${entry.sha256}`, `${label} digest differs from exact artifact metadata`);
+    if (requireExecutable) requireValue((fs.statSync(file).mode & 0o111) !== 0, `${label} is not executable`);
+    return { path: entry.path, file, sha256: entry.sha256 };
+  });
+  requireValue(declared.has(artifact.binaryPath), "binary metadata executableFiles must include scenario.artifact.binaryPath");
+  const binary = files.find((entry) => entry.path === artifact.binaryPath);
+  const metadataBinarySha256 = String(metadata.sha256 || "").replace(/^sha256:/u, "");
+  requireValue(/^[0-9a-f]{64}$/u.test(metadataBinarySha256) && metadataBinarySha256 === binary.sha256, "binary digest differs from exact artifact metadata");
+  return { metadata, files };
+}
+
+export function prepareArtifact({ artifactRoot, scenarioPath }) {
+  const scenario = validateScenario(readJson(path.resolve(scenarioPath), "scenario"));
+  const closure = validateExecutableClosure({ artifactRoot, scenario, requireExecutable: false });
+  for (const entry of closure.files) fs.chmodSync(entry.file, 0o755);
+  validateExecutableClosure({ artifactRoot, scenario, requireExecutable: true });
+  return {
+    executableFiles: closure.files.map(({ path: relative, sha256 }) => ({ path: relative, sha256 })),
+    metadataRoot: rootJson(closure.metadata),
+    authority: { classification: "artifact-mode-restoration", grants: [], nonAuthorities: NON_AUTHORITIES },
+  };
+}
+
 function validateExecution(execution) {
   exactKeys(execution, ["deterministic", "network", "secrets", "totalTimeoutSeconds", "environment"], ["durationClass"], "scenario.execution");
   requireValue(execution.deterministic === true && execution.network === "none" && execution.secrets === "none", "scenario execution must be deterministic, network-disabled, and secret-free");
@@ -185,7 +234,7 @@ function validateDemo(demo, index, demoIds, maximumSeconds) {
 }
 
 export function validateScenario(value) {
-  exactKeys(value, ["schema", "product", "artifact", "execution", "renditions", "demos", "publication", "authority"], [], "scenario");
+  exactKeys(value, ["schema", "product", "artifact", "execution", "renditions", "demos", "publication", "authority"], ["transportSmoke"], "scenario");
   requireValue(value.schema === "buildchain.declarative-binary-demo/v1", "unsupported scenario schema");
   validateProduct(value.product);
   validateArtifact(value.artifact);
@@ -194,6 +243,7 @@ export function validateScenario(value) {
   requireValue(Array.isArray(value.demos) && value.demos.length >= 1 && value.demos.length <= 8, "scenario requires 1 through 8 demos");
   const demoIds = new Set();
   value.demos.forEach((demo, index) => validateDemo(demo, index, demoIds, executionPolicy.maximumSeconds));
+  if (value.transportSmoke) validateTransportSmoke(value.transportSmoke);
   exactKeys(value.publication, ["evidencePath", "readmePath", "marker"], [], "scenario.publication");
   inside("/repository", value.publication.evidencePath, "scenario.publication.evidencePath");
   inside("/repository", value.publication.readmePath, "scenario.publication.readmePath");
@@ -474,6 +524,14 @@ function main(argv = process.argv.slice(2)) {
     process.stdout.write(stableJson(scenario.publication));
     return;
   }
+  if (command === "prepare-artifact") {
+    const result = prepareArtifact({
+      artifactRoot: path.resolve(args["artifact-root"]),
+      scenarioPath: path.resolve(args.scenario),
+    });
+    process.stdout.write(stableJson({ ok: true, ...result }));
+    return;
+  }
   if (command === "adapt") {
     const result = adaptCapture({ artifactRoot: path.resolve(args["artifact-root"]), output: path.resolve(args.output) });
     process.stdout.write(stableJson({ ok: true, ...result }));

package/scripts/auditable-demo-transport-smoke.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// 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 { pathToFileURL } from "node:url";
+
+import {
+  prepareArtifact,
+  validateScenario,
+} from "./auditable-demo-platform.mjs";
+
+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 });
+  }
+}
+
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2)
+    values[argv[index].replace(/^--/u, "")] = argv[index + 1];
+  return values;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, ...runTransportSmoke({ artifactRoot: args["artifact-root"], scenarioPath: args.scenario }) }, null, 2)}\n`,
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}