@kungfu-tech/buildchain 3.0.2-alpha.7 → 3.0.2-alpha.9

package/scripts/check-inventory.mjs

@@ -71,6 +71,11 @@ const requiredPaths = [
   "docs/github-artifact-attestation.md",
   "docs/shifu-gate-profiles.md",
   "docs/auditable-demo.md",
+  "contracts/auditable-demo-media-profiles-v1.json",
+  "contracts/evidence/auditable-demo-web-delivery-v1.json",
+  "contracts/fixtures/auditable-demo-web-delivery-v1/complete-transcript.txt",
+  "contracts/fixtures/auditable-demo-web-delivery-v1/public-projection.json",
+  "contracts/fixtures/auditable-demo-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -54,6 +54,17 @@ function integer(value, fallback) {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
 
+function pullRequestBodyPrefix(value) {
+  const normalized = String(value ?? "").trim();
+  if (normalized.length > 32768)
+    throw new Error("pullRequestBodyPrefix exceeds 32768 characters");
+  if (normalized.includes(STATE_MARKER_START))
+    throw new Error(
+      "pullRequestBodyPrefix must not contain the managed candidate state marker",
+    );
+  return normalized;
+}
+
 function canonical(value) {
   if (Array.isArray(value)) return value.map(canonical);
   if (value && typeof value === "object") {
@@ -210,6 +221,10 @@ export function normalizeDevAlphaPatrolOptions(options = {}) {
         process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS,
       7 * 24 * 60 * 60,
     ),
+    pullRequestBodyPrefix: pullRequestBodyPrefix(
+      options.pullRequestBodyPrefix ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_PR_BODY_PREFIX,
+    ),
     createPullRequest,
     settlementAuthorized: bool(
       options.settlementAuthorized ??
@@ -405,6 +420,9 @@ function pullRequestBody({
   state,
 }) {
   return [
+    ...(options.pullRequestBodyPrefix
+      ? [options.pullRequestBodyPrefix, ""]
+      : []),
     LEGACY_BODY_MARKER,
     "",
     `- Source branch: \`${options.sourceBranch}\``,

package/scripts/dispatch-artifact-signing-authority.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function repository(value, label) {
+  const normalized = required(value, label);
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(normalized)) throw new Error(`${label} must be owner/repository`);
+  return normalized;
+}
+
+const TRANSIENT_GITHUB_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+
+function retryDelayMs(attempt) {
+  return Math.min(1_000 * (2 ** (attempt - 1)), 10_000);
+}
+
+export async function githubRequest(url, {
+  token,
+  method = "GET",
+  body,
+  fetchImpl = fetch,
+  delayImpl = delay,
+  maxAttempts = 5,
+  warnImpl = console.warn,
+} = {}) {
+  const methodName = String(method).toUpperCase();
+  const retrySafe = methodName === "GET";
+  const requestedAttempts = Number(maxAttempts);
+  const attemptLimit = retrySafe && Number.isSafeInteger(requestedAttempts) && requestedAttempts > 0
+    ? requestedAttempts
+    : 1;
+  for (let attempt = 1; attempt <= attemptLimit; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(`https://api.github.com${url}`, {
+        method: methodName,
+        headers: {
+          Accept: "application/vnd.github+json",
+          Authorization: `Bearer ${token}`,
+          "X-GitHub-Api-Version": "2022-11-28",
+          "User-Agent": "kungfu-buildchain-artifact-signing",
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch (error) {
+      if (retrySafe && attempt < attemptLimit) {
+        warnImpl(`Buildchain signing authority: GitHub API GET transport failure; retry ${attempt + 1}/${attemptLimit}`);
+        await delayImpl(retryDelayMs(attempt));
+        continue;
+      }
+      throw error;
+    }
+    if (!response.ok) {
+      const text = await response.text();
+      if (retrySafe && TRANSIENT_GITHUB_STATUSES.has(response.status) && attempt < attemptLimit) {
+        warnImpl(`Buildchain signing authority: GitHub API GET returned ${response.status}; retry ${attempt + 1}/${attemptLimit}`);
+        await delayImpl(retryDelayMs(attempt));
+        continue;
+      }
+      throw new Error(`GitHub API ${methodName} ${url} failed (${response.status}): ${text.slice(0, 500)}`);
+    }
+    if (response.status === 204) return {};
+    try {
+      return await response.json();
+    } catch (error) {
+      if (retrySafe && attempt < attemptLimit) {
+        warnImpl(`Buildchain signing authority: GitHub API GET response failed to decode; retry ${attempt + 1}/${attemptLimit}`);
+        await delayImpl(retryDelayMs(attempt));
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("GitHub API retry loop exhausted");
+}
+
+export async function dispatchArtifactSigningAuthority({
+  token = process.env.BUILDCHAIN_AUTHORITY_DISPATCH_TOKEN,
+  authorityRepository = process.env.BUILDCHAIN_AUTHORITY_REPOSITORY || "kungfu-systems/buildchain",
+  authorityRef = process.env.BUILDCHAIN_AUTHORITY_REF,
+  sourceRepository = process.env.GITHUB_REPOSITORY,
+  sourceRunId = process.env.GITHUB_RUN_ID,
+  sourceRunAttempt = process.env.GITHUB_RUN_ATTEMPT || "1",
+  requestArtifact = process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT,
+  runtimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
+  resultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT,
+  timeoutSeconds = process.env.BUILDCHAIN_SIGNING_TIMEOUT_SECONDS || "7200",
+} = {}) {
+  const authToken = required(token, "Buildchain authority dispatch token");
+  const authorityRepo = repository(authorityRepository, "authority repository");
+  const sourceRepo = repository(sourceRepository, "source repository");
+  const ref = required(authorityRef, "authority ref");
+  const runtime = required(runtimeSha, "Buildchain runtime SHA");
+  if (!/^[0-9a-f]{40}$/u.test(runtime)) throw new Error("Buildchain runtime SHA must be exact");
+  const correlationId = `${required(sourceRunId, "source run ID")}-${required(sourceRunAttempt, "source run attempt")}-${runtime.slice(0, 12)}-${required(requestArtifact, "request artifact").replace(/[^A-Za-z0-9._-]+/gu, "-")}`;
+  const resultName = required(resultArtifact, "result artifact");
+  const workflow = "artifact-signing-authority.yml";
+  const startedAt = Date.now() - 30_000;
+  await githubRequest(`/repos/${authorityRepo}/actions/workflows/${workflow}/dispatches`, {
+    token: authToken,
+    method: "POST",
+    body: {
+      ref,
+      inputs: {
+        "source-repository": sourceRepo,
+        "source-run-id": String(sourceRunId),
+        "request-artifact-pattern": required(requestArtifact, "request artifact"),
+        "result-artifact-name": resultName,
+        "correlation-id": correlationId,
+        "expected-runtime-sha": runtime,
+      },
+    },
+  });
+  const deadline = Date.now() + Number(timeoutSeconds) * 1000;
+  let run;
+  while (Date.now() < deadline) {
+    const response = await githubRequest(`/repos/${authorityRepo}/actions/workflows/${workflow}/runs?event=workflow_dispatch&per_page=50`, { token: authToken });
+    run = (response.workflow_runs || []).find((entry) =>
+      new Date(entry.created_at).getTime() >= startedAt &&
+      String(entry.display_title || "").includes(correlationId),
+    );
+    if (run?.status === "completed") break;
+    await delay(10_000);
+  }
+  if (!run || run.status !== "completed") throw new Error("timed out waiting for Buildchain signing authority");
+  if (run.conclusion !== "success") throw new Error(`Buildchain signing authority failed: ${run.html_url}`);
+  writeGitHubOutputs({
+    "authority-run-id": String(run.id),
+    "authority-run-url": run.html_url,
+    "result-artifact": resultName,
+    "correlation-id": correlationId,
+  });
+  return { runId: run.id, runUrl: run.html_url, resultArtifact: resultName, correlationId };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    await dispatchArtifactSigningAuthority();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/finalize-native-artifact-signing-result.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { createArtifactSigningReceipt, validateArtifactSigningRequest } from "../packages/core/artifact-signing.js";
+import { artifactSigningEvidenceDigest, createArtifactSigningResult } from "../packages/core/artifact-signing-result.js";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function sha256File(filePath) {
+  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+}
+
+function resolveBelow(root, relative, label) {
+  const target = path.resolve(root, required(relative, label));
+  const rel = path.relative(path.resolve(root), target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`${label} escapes its root`);
+  return target;
+}
+
+export function finalizeNativeArtifactSigningResult({
+  requestRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
+  requestPath = process.env.BUILDCHAIN_SIGNING_REQUEST_PATH,
+  signedPayload = process.env.BUILDCHAIN_SIGNED_PAYLOAD,
+  evidencePath = process.env.BUILDCHAIN_SIGNING_EVIDENCE,
+  outputRoot = process.env.BUILDCHAIN_SIGNING_RESULT_ROOT,
+  checks = process.env.BUILDCHAIN_SIGNING_VERIFICATION_CHECKS,
+} = {}) {
+  const requests = path.resolve(required(requestRoot, "signing request root"));
+  const request = JSON.parse(fs.readFileSync(resolveBelow(requests, requestPath, "request path"), "utf8"));
+  const requestCheck = validateArtifactSigningRequest(request);
+  if (!requestCheck.ok) throw new Error(`invalid signing request: ${requestCheck.issues.join(", ")}`);
+  if (request.signature.semantics !== "native-platform-signature") {
+    throw new Error("native result finalizer rejects non-native signature profiles");
+  }
+  const payloadSource = path.resolve(required(signedPayload, "signed payload"));
+  const evidenceSource = path.resolve(required(evidencePath, "signing evidence"));
+  const resultDirectory = path.resolve(required(outputRoot, "signing result root"));
+  fs.mkdirSync(path.join(resultDirectory, "payload"), { recursive: true });
+  const payloadPath = path.join(resultDirectory, "payload", path.basename(payloadSource));
+  fs.copyFileSync(payloadSource, payloadPath, fs.constants.COPYFILE_EXCL);
+  const evidenceOutput = path.join(resultDirectory, "provider-evidence.json");
+  fs.copyFileSync(evidenceSource, evidenceOutput, fs.constants.COPYFILE_EXCL);
+  const evidenceDocument = JSON.parse(fs.readFileSync(evidenceOutput, "utf8"));
+  if (evidenceDocument.status !== "passed" || evidenceDocument.provider !== request.signature.provider) {
+    throw new Error("provider evidence does not prove the requested native signature");
+  }
+  const evidence = [{ kind: `${request.signature.profile}-verification`, path: "provider-evidence.json", digest: sha256File(evidenceOutput) }];
+  const payloadDigest = sha256File(payloadPath);
+  const receipt = createArtifactSigningReceipt({
+    request,
+    result: { artifactDigest: payloadDigest, evidenceDigest: artifactSigningEvidenceDigest(evidence) },
+    signatures: [{ kind: request.signature.profile, digest: evidence[0].digest }],
+  });
+  fs.writeFileSync(path.join(resultDirectory, "receipt.json"), `${JSON.stringify(receipt, null, 2)}\n`);
+  const verificationChecks = String(checks || "").split(",").map((value) => value.trim()).filter(Boolean);
+  const result = createArtifactSigningResult({
+    request,
+    receipt,
+    payload: { path: `payload/${path.basename(payloadPath)}`, bytes: fs.statSync(payloadPath).size, digest: payloadDigest },
+    evidence,
+    verification: { status: "passed", provider: request.signature.provider, checks: verificationChecks },
+  });
+  fs.writeFileSync(path.join(resultDirectory, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
+  const index = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-artifact-signing-result-index/v1",
+    results: [{
+      id: request.artifact.id,
+      requestDigest: request.digest,
+      resultDigest: result.digest,
+      result: "result.json",
+      payload: result.artifact.path,
+      receipt: "receipt.json",
+    }],
+  };
+  fs.writeFileSync(path.join(resultDirectory, "index.json"), `${JSON.stringify(index, null, 2)}\n`);
+  writeGitHubOutputs({ "result-root": resultDirectory, "result-index": path.join(resultDirectory, "index.json") });
+  return index;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    finalizeNativeArtifactSigningResult();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-site-bundle.mjs

@@ -533,6 +533,9 @@ function nodeApiMeta(exportName) {
     "./github-governance-authority": { group: "governance-versioning", summary: "Fail-closed GitHub ownership, effective-policy, managed-zone admission, rollout-plan, and immutable receipt APIs." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
+    "./artifact-signing": { group: "reusable-build", summary: "Credential-free artifact signing declarations, source-bound requests, authority receipts, profile resolution, and fail-closed validation APIs." },
+    "./artifact-signing-result": { group: "release-passport-trust", summary: "Immutable signed-result, final-payload, receipt, evidence-root, and provider-verification binding APIs." },
+    "./detached-artifact-signature": { group: "release-passport-trust", summary: "Buildchain-authority Ed25519 detached signature and verification APIs for arbitrary binary artifacts." },
     "./anchored-version-material": { group: "reusable-build", summary: "Anchored/manual derived version material preflight, exact-tree binding, and digest evidence APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./github-artifact-attestation": { group: "release-passport-trust", summary: "GitHub keyless artifact attestation policy, predicate, provider evidence, and fail-closed verification APIs." },

package/scripts/import-artifact-signing-results.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateArtifactSigningRequest } from "../packages/core/artifact-signing.js";
+import { verifyArtifactSigningResults } from "./verify-artifact-signing-results.mjs";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function resolveBelow(root, relative, label) {
+  const target = path.resolve(root, required(relative, label));
+  const rel = path.relative(path.resolve(root), target);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`${label} must resolve below its root`);
+  return target;
+}
+
+export function importArtifactSigningResults({
+  workspace = process.env.GITHUB_WORKSPACE || process.cwd(),
+  cwd = process.env.BUILDCHAIN_SIGNING_CWD || ".",
+  requestRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
+  resultRoot = process.env.BUILDCHAIN_SIGNING_RESULT_ROOT,
+  evidenceRoot = process.env.BUILDCHAIN_SIGNING_IMPORTED_EVIDENCE_ROOT || ".buildchain/artifacts/signing",
+} = {}) {
+  const sourceRoot = path.resolve(workspace, cwd);
+  const requests = path.resolve(required(requestRoot, "signing request root"));
+  const results = path.resolve(required(resultRoot, "signing result root"));
+  const verification = verifyArtifactSigningResults({ requestRoot: requests, resultRoot: results });
+  const requestIndex = JSON.parse(fs.readFileSync(path.join(requests, "index.json"), "utf8"));
+  const resultIndex = JSON.parse(fs.readFileSync(path.join(results, "index.json"), "utf8"));
+  const byId = new Map();
+  for (const entry of requestIndex.requests || []) {
+    const request = JSON.parse(fs.readFileSync(resolveBelow(requests, entry.path, "request path"), "utf8"));
+    const check = validateArtifactSigningRequest(request);
+    if (!check.ok || request.digest !== entry.digest) throw new Error(`invalid request during result import: ${entry.id}`);
+    byId.set(entry.id, request);
+  }
+  const imported = [];
+  for (const entry of resultIndex.results || []) {
+    const request = byId.get(entry.id);
+    if (!request) throw new Error(`result has no local sealed request: ${entry.id}`);
+    const resultPath = resolveBelow(results, entry.result, "result path");
+    const result = JSON.parse(fs.readFileSync(resultPath, "utf8"));
+    const payload = resolveBelow(path.dirname(resultPath), result.artifact.path, "signed payload");
+    const target = resolveBelow(sourceRoot, request.artifact.path, "consumer artifact path");
+    const mode = fs.statSync(target).mode;
+    fs.copyFileSync(payload, target);
+    fs.chmodSync(target, mode);
+    const destination = path.resolve(sourceRoot, evidenceRoot, entry.id);
+    const rel = path.relative(sourceRoot, destination);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error("imported signing evidence escapes consumer source root");
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.cpSync(path.dirname(resultPath), destination, { recursive: true, force: false, errorOnExist: true });
+    imported.push({ id: entry.id, path: request.artifact.path, resultDigest: result.digest });
+  }
+  writeGitHubOutputs({
+    "imported-count": String(imported.length),
+    "imported-json": JSON.stringify(imported),
+    "evidence-root": path.resolve(sourceRoot, evidenceRoot),
+  });
+  return { ...verification, imported };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    importArtifactSigningResults();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/inspect-artifact-signing-requests.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateArtifactSigningRequest } from "../packages/core/artifact-signing.js";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function safeId(value) {
+  const normalized = String(value || "")
+    .replace(/[^A-Za-z0-9._-]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  if (!normalized || normalized === "." || normalized === "..") {
+    throw new Error("unsafe signing request id");
+  }
+  return normalized;
+}
+
+function walk(root, name, output = []) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const child = path.join(root, entry.name);
+    if (entry.isDirectory()) walk(child, name, output);
+    else if (entry.isFile() && entry.name === name) output.push(child);
+  }
+  return output;
+}
+
+export function inspectArtifactSigningRequests({
+  inputRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
+  expectedRepository = process.env.BUILDCHAIN_SIGNING_SOURCE_REPOSITORY,
+  expectedRuntimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
+} = {}) {
+  const root = path.resolve(required(inputRoot, "signing request root"));
+  const indexes = walk(root, "index.json");
+  if (indexes.length === 0) throw new Error("no artifact signing request indexes found");
+  const seen = new Set();
+  const matrices = {
+    detached: [],
+    macos: [],
+    windows: [],
+  };
+  for (const indexPath of indexes) {
+    const index = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+    if (index.contract !== "kungfu-buildchain-artifact-signing-request-index/v1") continue;
+    for (const entry of index.requests || []) {
+      const requestPath = path.resolve(path.dirname(indexPath), entry.path);
+      const relative = path.relative(root, requestPath);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("signing request path escapes the authority intake root");
+      }
+      const request = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+      const check = validateArtifactSigningRequest(request);
+      if (!check.ok || request.digest !== entry.digest) {
+        throw new Error(`invalid artifact signing request: ${entry.id}`);
+      }
+      if (expectedRepository && request.source.repository !== expectedRepository) {
+        throw new Error("signing request source repository mismatch");
+      }
+      if (expectedRuntimeSha && request.runtime.sha !== expectedRuntimeSha) {
+        throw new Error("signing request runtime SHA mismatch");
+      }
+      const key = `${request.source.sha}:${request.artifact.id}:${request.artifact.platform}`;
+      if (seen.has(key)) throw new Error(`duplicate artifact signing request: ${key}`);
+      seen.add(key);
+      const item = {
+        id: request.artifact.id,
+        slug: safeId(request.artifact.id),
+        request: path.relative(root, requestPath).split(path.sep).join("/"),
+        directory: path.relative(root, path.dirname(requestPath)).split(path.sep).join("/"),
+        indexRoot: path.relative(root, path.dirname(indexPath)).split(path.sep).join("/") || ".",
+      };
+      if (request.signature.profile === "detached-signature-v1") matrices.detached.push(item);
+      else if (request.signature.profile === "apple-developer-id") matrices.macos.push(item);
+      else if (request.signature.profile === "windows-authenticode") matrices.windows.push(item);
+      else throw new Error(`unsupported signing authority profile: ${request.signature.profile}`);
+    }
+  }
+  for (const entries of Object.values(matrices)) entries.sort((a, b) => a.request.localeCompare(b.request));
+  writeGitHubOutputs({
+    "detached-matrix": JSON.stringify(matrices.detached),
+    "macos-matrix": JSON.stringify(matrices.macos),
+    "windows-matrix": JSON.stringify(matrices.windows),
+    "request-count": String(seen.size),
+  });
+  return matrices;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    inspectArtifactSigningRequests();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/materialize-artifact-signing-request.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateArtifactSigningRequest } from "../packages/core/artifact-signing.js";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function resolveBelow(root, relative, label) {
+  const target = path.resolve(root, required(relative, label));
+  const rel = path.relative(path.resolve(root), target);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`${label} must resolve below its root`);
+  return target;
+}
+
+function sha256File(filePath) {
+  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+}
+
+export function materializeArtifactSigningRequest({
+  requestRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
+  requestPath = process.env.BUILDCHAIN_SIGNING_REQUEST_PATH,
+  expectedProfile = process.env.BUILDCHAIN_SIGNING_EXPECTED_PROFILE,
+  outputPath = process.env.BUILDCHAIN_UNSIGNED_OUTPUT,
+} = {}) {
+  const root = path.resolve(required(requestRoot, "signing request root"));
+  const requestFile = resolveBelow(root, requestPath, "request path");
+  const request = JSON.parse(fs.readFileSync(requestFile, "utf8"));
+  const check = validateArtifactSigningRequest(request);
+  if (!check.ok) throw new Error(`invalid artifact signing request: ${check.issues.join(", ")}`);
+  if (expectedProfile && request.signature.profile !== expectedProfile) throw new Error("artifact signing profile mismatch");
+  if (request.artifact.transport?.format !== "exact-file") throw new Error("native executable signing requires exact-file transport");
+  const requestIndexRoot = path.dirname(path.dirname(requestFile));
+  const payload = resolveBelow(requestIndexRoot, request.artifact.transport.file, "transport payload");
+  const stat = fs.statSync(payload);
+  const payloadDigest = sha256File(payload);
+  if (!stat.isFile() || stat.size !== request.artifact.transport.bytes || stat.size !== request.artifact.bytes || payloadDigest !== request.artifact.transport.digest || payloadDigest !== request.artifact.digest) {
+    throw new Error("signing payload does not match its sealed request");
+  }
+  const output = path.resolve(required(outputPath, "unsigned output path"));
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.copyFileSync(payload, output, fs.constants.COPYFILE_EXCL);
+  writeGitHubOutputs({
+    "artifact-id": request.artifact.id,
+    "payload-path": output,
+    "request-digest": request.digest,
+    "signature-provider": request.signature.provider,
+  });
+  return { request, output };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    materializeArtifactSigningRequest();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/merge-artifact-signing-results.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function safeId(value) {
+  const normalized = String(value || "").replace(/[^A-Za-z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "");
+  if (!normalized || normalized === "." || normalized === "..") throw new Error("unsafe signing result id");
+  return normalized;
+}
+
+function walk(root, output = []) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const child = path.join(root, entry.name);
+    if (entry.isDirectory()) walk(child, output);
+    else if (entry.isFile() && entry.name === "index.json") output.push(child);
+  }
+  return output;
+}
+
+export function mergeArtifactSigningResults({
+  inputRoot = process.env.BUILDCHAIN_SIGNING_RESULT_INPUT_ROOT,
+  outputRoot = process.env.BUILDCHAIN_SIGNING_RESULT_ROOT,
+} = {}) {
+  const input = path.resolve(required(inputRoot, "signing result input root"));
+  const output = path.resolve(required(outputRoot, "signing result output root"));
+  fs.mkdirSync(output, { recursive: true });
+  const merged = [];
+  const seen = new Set();
+  for (const indexPath of walk(input)) {
+    const index = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+    if (index.contract !== "kungfu-buildchain-artifact-signing-result-index/v1") continue;
+    for (const entry of index.results || []) {
+      if (seen.has(entry.id)) throw new Error(`duplicate signing result: ${entry.id}`);
+      seen.add(entry.id);
+      const sourceResult = path.resolve(path.dirname(indexPath), entry.result);
+      const sourceDirectory = path.dirname(sourceResult);
+      const relative = path.relative(path.dirname(indexPath), sourceDirectory);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("signing result escapes provider root");
+      const destinationName = safeId(entry.id);
+      const destination = path.join(output, destinationName);
+      fs.cpSync(sourceDirectory, destination, { recursive: true, errorOnExist: true, force: false });
+      merged.push({
+        ...entry,
+        result: `${destinationName}/${path.basename(sourceResult)}`,
+        ...(entry.payload ? { payload: `${destinationName}/${path.relative(sourceDirectory, path.resolve(path.dirname(indexPath), entry.payload)).split(path.sep).join("/")}` } : {}),
+        ...(entry.envelope ? { envelope: `${destinationName}/${path.relative(sourceDirectory, path.resolve(path.dirname(indexPath), entry.envelope)).split(path.sep).join("/")}` } : {}),
+        ...(entry.receipt ? { receipt: `${destinationName}/${path.relative(sourceDirectory, path.resolve(path.dirname(indexPath), entry.receipt)).split(path.sep).join("/")}` } : {}),
+      });
+    }
+  }
+  if (merged.length === 0) throw new Error("no artifact signing results found");
+  merged.sort((a, b) => a.id.localeCompare(b.id));
+  const index = { schemaVersion: 1, contract: "kungfu-buildchain-artifact-signing-result-index/v1", results: merged };
+  const indexPath = path.join(output, "index.json");
+  fs.writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`);
+  writeGitHubOutputs({ "result-count": String(merged.length), "result-index": indexPath, "result-root": output });
+  return index;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    mergeArtifactSigningResults();
+  } catch (error) {
+    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    process.exitCode = 1;
+  }
+}