@kungfu-tech/buildchain 2.12.7-alpha.8 → 2.12.7

package/docs/publication-artifacts.md

@@ -196,16 +196,21 @@ jobs:
       verify-command: make check
       artifact-paths: _build/paper-name.pdf
       buildchain-contract-lock-path: .buildchain/contract-lock.json
+    secrets:
+      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
 ```
 
-The sealed preset does not accept a long-lived promotion token. It builds and
-packages the paper in a read-only job, then a credential-free authority job
-downloads that exact candidate, audits the external control plane, and seals a
-capability over the source tree, Buildchain runtime, controller receipt, PDF,
-and npm package bytes. Only the final job receives write and OIDC permissions;
-it downloads the admitted candidate, recomputes the capability binding, and
-publishes without executing consumer build commands. npm binds the OIDC identity
-to the consumer workflow named by `publisher-workflow-path`.
+The sealed preset does not use a long-lived token for npm publication. It may
+accept an optional `BUILDCHAIN_PROMOTION_TOKEN` only for machine-generated
+version-state updates on protected channel branches; npm publication remains
+bound to GitHub OIDC trusted publishing. The preset builds and packages the
+paper in a read-only job, then a credential-free authority job downloads that
+exact candidate, audits the external control plane, and seals a capability over
+the source tree, Buildchain runtime, controller receipt, PDF, and npm package
+bytes. Only the final job receives write and OIDC permissions; it downloads the
+admitted candidate, recomputes the capability binding, and publishes without
+executing consumer build commands. npm binds the OIDC identity to the consumer
+workflow named by `publisher-workflow-path`.
 
 The preset:
 

package/docs/publication-authority.md

@@ -109,17 +109,20 @@ artifacts. The denial explicitly records that npm Trusted Publishing and OIDC
 were not evaluated, so downstream diagnostics cannot misclassify an admission
 assembly failure as an npm authentication failure.
 
-Buildchain's own `workflow_run` promotion lane may assemble those inputs only
-for `kungfu-systems/buildchain`. It downloads the exact prior RC passport,
+An explicitly opted-in managed `workflow_run` promotion lane may assemble those
+inputs from evidence owned by its caller repository. It downloads the exact prior RC passport,
 summary, referenced controller receipt, manifests, and product payloads; proves
 the admitted channel commit has the same Git tree as the RC; performs the live
 read-only control-plane audit; records the GitHub-hosted job as ephemeral runner
-provenance; and creates an explicit Buildchain-owned no-Gate decision. The
+provenance; and consumes either a caller-supplied Gate aggregate or an explicit
+caller no-Gate decision. The
 independent verifier then recomputes every receipt and payload digest exactly as
-it does for externally supplied admission. The self-assembly mode rejects other
-repositories, unknown refs, non-exact source SHAs, and any caller other than
-`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external
-consumer workflows still require their own explicit admission inputs.
+it does for externally supplied admission. Automatic assembly keeps Buildchain
+as the canonical authority repository, requires evidence to belong to the
+caller, binds a repository-local publisher workflow, and rejects unknown refs,
+non-exact source SHAs, package/target mismatches, or an undeclared Gate policy.
+Manual apply and consumers that do not opt in still require their own explicit
+admission inputs.
 
 Before authority verification, the reusable promotion controller runs the same
 release transaction selector in read-only mode. That plan supplies one exact

package/docs/release-candidate.md

@@ -116,3 +116,22 @@ KFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and
 compares KFD-3 declared shipped public surfaces with artifact-exposed public
 surfaces. The release passport records the results under `kfd-1`, `kfd-2`, and
 the KFD-provided `kfd-3` section.
+
+Managed consumers may also ask the promotion wrapper to assemble sealed
+publication evidence from the exact release candidate instead of producing
+short-lived admission JSON in repository-specific workflow code:
+
+```yaml
+      publication-auto-admission: true
+      publication-auto-no-gate: true
+      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml
+      publication-product: Example Product
+      publication-target: npm:@example/product
+      publication-package-name: "@example/product"
+```
+
+`publication-auto-no-gate` is an explicit consumer decision, not a default. A
+consumer with a Shifu Gate registry supplies `publication-gate-aggregate-json`
+instead. Buildchain still requires caller-owned RC evidence, an exact authority
+runtime and source SHA, a repository-local publisher workflow, matching npm
+target/package identity, and a qualifying control-plane audit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.7-alpha.8",
+  "version": "2.12.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/index.js

@@ -157,6 +157,7 @@ export {
   PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
   createPublicationArtifactCandidate,
   publicationArtifactCandidateDigest,
+  resolvePublicationCandidateFile,
 } from "./publication-artifact-candidate.js";
 
 export {

package/packages/core/publication-artifact-candidate.js

@@ -20,6 +20,18 @@ export function publicationArtifactCandidateDigest(value) {
   return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
 }
 
+export function resolvePublicationCandidateFile(files = [], candidatePath) {
+  const normalizedPath = requiredString(candidatePath, "candidatePath").replaceAll("\\", "/");
+  if (normalizedPath.startsWith("/") || normalizedPath.split("/").includes("..")) {
+    throw new Error(`publication artifact candidate contains an unsafe path: ${normalizedPath}`);
+  }
+  const matches = files.filter((entry) => entry.path === normalizedPath);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one publication candidate file at ${normalizedPath}, found ${matches.length}`);
+  }
+  return matches[0].path;
+}
+
 function requiredString(value, label) {
   const normalized = String(value || "").trim();
   if (!normalized) throw new Error(`${label} must be a non-empty string`);

package/scripts/assemble-self-publication-admission.mjs

@@ -115,13 +115,22 @@ async function main() {
     manifests,
     payloads: manifests.map((manifest) => payloadFor(manifest, path.join(evidenceRoot, "payloads"))),
   });
-  const gateAggregate = createPublicationGateDecision({
-    sourceSha,
-    profile: process.env.BUILDCHAIN_GATE_PROFILE || "buildchain-self-publication",
-    required: false,
-    rationale: process.env.BUILDCHAIN_GATE_RATIONALE || "Buildchain self-publication has no consumer-owned Shifu Gate registry.",
-    policy: { scope: "buildchain-self-publication", repository },
-  });
+  const suppliedGateAggregate = String(process.env.BUILDCHAIN_GATE_AGGREGATE_JSON || "").trim();
+  let gateAggregate;
+  if (suppliedGateAggregate) {
+    gateAggregate = JSON.parse(suppliedGateAggregate);
+  } else {
+    if (process.env.BUILDCHAIN_ALLOW_NO_GATE !== "true") {
+      throw new Error("managed release-candidate admission requires a Gate aggregate or explicit no-Gate decision");
+    }
+    gateAggregate = createPublicationGateDecision({
+      sourceSha,
+      profile: process.env.BUILDCHAIN_GATE_PROFILE || "managed-release-candidate-no-gate",
+      required: false,
+      rationale: process.env.BUILDCHAIN_GATE_RATIONALE || "The consumer explicitly declared no Shifu Gate registry for this publication transaction.",
+      policy: { scope: "managed-release-candidate", repository },
+    });
+  }
   const runnerProvenance = createRunnerProvenance({
     runnerClass: "ephemeral",
     os: required("RUNNER_OS"),
@@ -178,6 +187,6 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error(`assemble self publication admission: ${error.message}`);
+  console.error(`assemble release-candidate admission: ${error.message}`);
   process.exitCode = 1;
 });

package/scripts/locked-source-checkout.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 export const LOCKED_SOURCE_CHECKOUT_CONTRACT = "kungfu-buildchain-locked-source-checkout-cache";
+export const ISOLATED_GIT_GLOBAL_CONFIG = process.platform === "win32" ? "NUL" : "/dev/null";
 
 const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
 
@@ -133,6 +134,24 @@ function githubAuthEnv(token = "") {
   };
 }
 
+function isolatedGitFetchEnv(env = {}, targetPath) {
+  const configuredCount = Number.parseInt(env.GIT_CONFIG_COUNT || "0", 10);
+  const safeDirectoryIndex = Number.isInteger(configuredCount) && configuredCount >= 0
+    ? configuredCount
+    : 0;
+  return {
+    ...env,
+    // Runner-global URL rewrites are shared mutable state. A concurrent job
+    // may point the same repository URL at a different single-SHA bundle, so
+    // network fetches must not consult the account-level Git config.
+    GIT_CONFIG_GLOBAL: ISOLATED_GIT_GLOBAL_CONFIG,
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_COUNT: String(safeDirectoryIndex + 1),
+    [`GIT_CONFIG_KEY_${safeDirectoryIndex}`]: "safe.directory",
+    [`GIT_CONFIG_VALUE_${safeDirectoryIndex}`]: path.resolve(targetPath),
+  };
+}
+
 function markSafeDirectory(targetPath, timeoutMs) {
   try {
     git(["config", "--global", "--add", "safe.directory", path.resolve(targetPath)], {
@@ -203,9 +222,32 @@ export function fetchSourceCommit({
   sourceTreeSha = "",
   timeoutMs,
   env = {},
+  allowFullFetchRetry = false,
   runGit = git,
   containsCommit = hasCommit,
 }) {
+  const fetchEnv = isolatedGitFetchEnv(env, targetPath);
+  const fetch = (refspec) => {
+    const options = { cwd: targetPath, timeoutMs, env: fetchEnv };
+    try {
+      runGit(["fetch", "--no-tags", "--depth=1", remoteName, refspec], options);
+      return "shallow";
+    } catch (error) {
+      if (
+        !allowFullFetchRetry
+        || !/dumb http transport does not support shallow capabilities/i.test(
+          String(error?.message || error || ""),
+        )
+      ) {
+        throw error;
+      }
+      // Dumb HTTP mirrors are intentionally simple static cache endpoints.
+      // Retry only that explicit capability mismatch without --depth; all
+      // network fallbacks remain shallow and bounded by their own policy.
+      runGit(["fetch", "--no-tags", remoteName, refspec], options);
+      return "full";
+    }
+  };
   try {
     runGit(["remote", "remove", remoteName], { cwd: targetPath, timeoutMs, stdio: "ignore" });
   } catch {
@@ -219,13 +261,9 @@ export function fetchSourceCommit({
 
   if (fetchRef) {
     try {
-      runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${fetchRef}:refs/buildchain/source-ref`], {
-        cwd: targetPath,
-        timeoutMs,
-        env,
-      });
+      const fetchMode = fetch(`+${fetchRef}:refs/buildchain/source-ref`);
       if (containsCommit(targetPath, sha, timeoutMs)) {
-        return { selector: "ref", checkoutSha: sha };
+        return { selector: "ref", checkoutSha: sha, fetchMode };
       }
       if (/^refs\/pull\/\d+\/merge$/.test(fetchRef) && sourceTreeSha) {
         const fetchedSha = runGit(["rev-parse", "refs/buildchain/source-ref^{commit}"], {
@@ -237,7 +275,7 @@ export function fetchSourceCommit({
           timeoutMs,
         });
         if (fetchedTree === sourceTreeSha) {
-          return { selector: "ref-tree", checkoutSha: fetchedSha };
+          return { selector: "ref-tree", checkoutSha: fetchedSha, fetchMode };
         }
       }
     } catch (error) {
@@ -249,15 +287,11 @@ export function fetchSourceCommit({
     }
   }
 
-  runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${sha}:refs/buildchain/source`], {
-    cwd: targetPath,
-    timeoutMs,
-    env,
-  });
+  const fetchMode = fetch(`+${sha}:refs/buildchain/source`);
   if (!containsCommit(targetPath, sha, timeoutMs)) {
     throw new Error(`fetched ${fetchRef || sha}, but ${sha} is not available`);
   }
-  return { selector: "sha", checkoutSha: sha };
+  return { selector: "sha", checkoutSha: sha, fetchMode };
 }
 
 export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onRetry = () => {}, shouldRetry = () => true }) {
@@ -413,7 +447,9 @@ export function lockedSourceCheckout({
           fetchRef,
           sourceTreeSha: treeSha,
           timeoutMs,
+          allowFullFetchRetry: true,
         });
+        evidence.cache.fetchMode = fetchResult.fetchMode;
         checkoutSha = fetchResult.checkoutSha || sha;
         checkoutFetchedCommit(targetPath, checkoutSha, timeoutMs);
       } else {
@@ -458,6 +494,7 @@ export function lockedSourceCheckout({
         shouldRetry: retryableGitFetchError,
       });
       evidence.cache.githubFetchAttempts = fetchResult.attempts;
+      evidence.cache.fetchMode = fetchResult.value.fetchMode;
       checkoutSha = fetchResult.value.checkoutSha || sha;
     } catch (error) {
       evidence.durationMs = Date.now() - startedAt;

package/scripts/publication-artifact-candidate.mjs

@@ -4,7 +4,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { createPublicationArtifactCandidate } from "../packages/core/publication-artifact-candidate.js";
+import {
+  createPublicationArtifactCandidate,
+  resolvePublicationCandidateFile,
+} from "../packages/core/publication-artifact-candidate.js";
+
+export { resolvePublicationCandidateFile };
 
 function flag(name, fallback = "") {
   const index = process.argv.indexOf(`--${name}`);
@@ -17,27 +22,16 @@ function requiredFlag(name) {
   return value;
 }
 
-function filesNamed(root, name) {
-  const matches = [];
-  const pending = [path.resolve(root)];
-  while (pending.length > 0) {
-    const current = pending.pop();
-    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-      const full = path.join(current, entry.name);
-      if (entry.isDirectory()) pending.push(full);
-      else if (entry.isFile() && entry.name === name) matches.push(full);
-    }
+function exactJson(root, relativePath) {
+  const absoluteRoot = path.resolve(root);
+  const absolutePath = path.resolve(absoluteRoot, relativePath);
+  if (!absolutePath.startsWith(`${absoluteRoot}${path.sep}`)) {
+    throw new Error(`publication evidence path escapes artifact root: ${relativePath}`);
   }
-  return matches.sort();
-}
-
-function oneJson(root, name) {
-  const matches = filesNamed(root, name);
-  if (matches.length !== 1)
-    throw new Error(
-      `expected exactly one ${name} under ${root}, found ${matches.length}`,
-    );
-  return JSON.parse(fs.readFileSync(matches[0], "utf8"));
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    throw new Error(`expected publication evidence at ${relativePath}`);
+  }
+  return JSON.parse(fs.readFileSync(absolutePath, "utf8"));
 }
 
 function collectFiles(root) {
@@ -79,12 +73,15 @@ export function buildPublicationArtifactCandidate({
     sourceSha,
     sourceTreeSha,
     runtimeSha,
-    manifest: oneJson(resolvedArtifactRoot, "publication-artifact.json"),
-    passport: oneJson(
+    manifest: exactJson(
+      resolvedArtifactRoot,
+      ".buildchain/publication/publication-artifact.json",
+    ),
+    passport: exactJson(
       resolvedArtifactRoot,
-      "publication-artifact-passport.json",
+      ".buildchain/publication/publication-artifact-passport.json",
     ),
-    controllerReceipt: oneJson(resolvedControllerRoot, "receipt.json"),
+    controllerReceipt: exactJson(resolvedControllerRoot, "receipt.json"),
     files: collectFiles(resolvedArtifactRoot),
   };
   const candidate = createPublicationArtifactCandidate(evidence);