@kungfu-tech/buildchain 3.0.2-alpha.0 → 3.0.2-alpha.10

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-channel-promotion-workflow.mjs

@@ -205,6 +205,8 @@ ${publicOutputs(outputs)}
 
 permissions:
   actions: write
+  artifact-metadata: write
+  attestations: write
   checks: write
   contents: write
   id-token: write
@@ -406,6 +408,8 @@ jobs:
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
     permissions:
       actions: write
+      artifact-metadata: write
+      attestations: write
       checks: write
       contents: write
       id-token: write
@@ -422,6 +426,8 @@ ${alphaForwarded}
     uses: kungfu-systems/buildchain/${stableRoute.workflowPath}@${stableRoute.callRef}
     permissions:
       actions: write
+      artifact-metadata: write
+      attestations: write
       checks: write
       contents: write
       id-token: write

package/scripts/generate-site-bundle.mjs

@@ -328,6 +328,7 @@ const manualMetaById = new Map(Object.entries({
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
+  "github-artifact-attestation": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 108 },
   "publication-authority": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 105 },
   "github-governance-authority": { capabilityGroup: "governance-versioning", audience: ["maintainer", "release-operator", "agent"], maturity: "preview", order: 106 },
   "controller-evidence": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator", "agent"], maturity: "draft", order: 205 },
@@ -337,6 +338,7 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
+  "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
@@ -404,6 +406,7 @@ function cliCommandMeta(id) {
     "collect-github-release": { group: "release-passport-trust", purpose: "Collect GitHub Release assets into a release passport." },
     create: { group: "release-passport-trust", purpose: "Create canonical sealed publication evidence documents." },
     "create-publication-admission": { group: "release-passport-trust", purpose: "Create a canonical short-lived publication admission envelope from exact consumer bindings." },
+    "create-github-artifact-attestation-policy": { group: "release-passport-trust", purpose: "Create an exact source, signer, Linux build, and Release Passport attestation policy." },
     "create-runner-provenance": { group: "release-passport-trust", purpose: "Create runner provenance evidence with an explicit qualification floor." },
     diagnostics: { group: "observability-diagnostics", purpose: "Inspect diagnostics command families." },
     "diagnostics-summary": { group: "observability-diagnostics", purpose: "Summarize diagnostics artifacts into JSON and cross-platform lifecycle timing tables." },
@@ -493,6 +496,7 @@ function cliCommandMeta(id) {
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
     "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
+    "verify-github-artifact-attestation": { group: "release-passport-trust", purpose: "Verify GitHub keyless attestation identity plus local artifact, manifest, Passport, predicate, bundle, and evidence bindings." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
     "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
     "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
@@ -516,6 +520,8 @@ function nodeApiMeta(exportName) {
     "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
+    "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
+    "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
     "./portable-dev-cache": { group: "observability-diagnostics", summary: "Portable dependency/compiler cache plan, exact-root verification, and provider receipt APIs." },
@@ -527,8 +533,12 @@ 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." },
     "./kfd-agent-hub": { group: "kfd-trust", summary: "Declarative Agent Hub adapter inspection, fixed-suite execution, exact KFD cut locking, and agent explanation APIs." },
     "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
@@ -603,6 +613,7 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
 }
 
 function workflowCapabilityGroup(entry) {
+  if (entry.id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
@@ -612,6 +623,7 @@ function workflowCapabilityGroup(entry) {
 }
 
 function actionCapabilityGroup(id) {
+  if (id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
   if (id === "promote-buildchain-ref") return capabilityGroup("release-passport-trust");
   if (id === "run-lifecycle" || id === "validate-config") return capabilityGroup("reusable-build");
   if (id === "report-buildchain-issue") return capabilityGroup("observability-diagnostics");
@@ -813,6 +825,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/stable-candidate-patrol.md",
+      "docs/dev-alpha-candidate-patrol.md",
       "docs/observed-evidence-patrol.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
@@ -894,11 +907,13 @@ function buildSiteBundle() {
         ["dev-pr-auto-merge", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
+        ["github-artifact-attestation", "release-passport"],
         ["buildchain-patrol", "repository-patrol"],
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
         ["stable-candidate-patrol", "repository-patrol"],
+        ["dev-alpha-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-qualification", "repository-patrol"],
         ["patrol-daily", "repository-patrol"],
@@ -986,6 +1001,7 @@ function buildSiteBundle() {
         "publish evidence JSON",
         "buildchain.release.json",
         "release passport assets",
+        "GitHub artifact attestation Sigstore bundle and Buildchain evidence JSON",
       ],
       owner: "promote-buildchain-ref",
     },
@@ -1018,6 +1034,10 @@ function buildSiteBundle() {
       "llms.txt",
       "buildchain-release-bundle.json",
       "buildchain-release-bundle.tar.gz",
+      "github-artifact-attestation.policy.json",
+      "github-artifact-attestation.predicate.json",
+      "github-artifact-attestation.evidence.json",
+      "attestation.sigstore.json",
     ],
     site: [
       "buildchain-site.json",

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;
+  }
+}