@kungfu-tech/buildchain 2.4.10-alpha.0 → 2.4.10-alpha.1

package/AGENTS.md

@@ -70,11 +70,16 @@ and rebuilds every action bundle.
 - Bugs, feature requests, questions, and documentation issues go through GitHub
   issues; security vulnerabilities use private vulnerability reporting - see
   [`SECURITY.md`](SECURITY.md).
+- Brand, hosted-service, and upstream-provider boundaries are documented in
+  [`TRADEMARK.md`](TRADEMARK.md), [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md), and
+  [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md).
 
 ## Ground rules
 
 - Never include secrets, credentials, tokens, or private logs in code, commits,
   issues, or pull requests.
+- Do not build or document official release integrations that bypass provider
+  protections, hide credential boundaries, or forge release evidence.
 - Keep generated action bundles in sync with source changes.
 - Keep documentation in sync with behavior, especially release governance and
   reusable workflow contracts.

package/LICENSE-POLICY.md

@@ -38,12 +38,28 @@ Apache-2.0 grants copyright and patent permissions. It does not grant trademark
 rights. Names, logos, domain names, and product marks such as "Kungfu" and
 "Buildchain" may be governed by separate brand guidelines.
 
+See [TRADEMARK.md](TRADEMARK.md) for the official project mark and fork identity
+boundary.
+
 ## Hosted and commercial services
 
 The open source license covers this repository. Hosted services, team features,
 enterprise support, managed deployments, commercial connectors, or other
 services offered by the project maintainers may use separate terms.
 
+See [ACCEPTABLE_USE.md](ACCEPTABLE_USE.md) for acceptable use of official hosted,
+managed, or maintainer-operated services.
+
+## Upstream provider integrations
+
+Official Buildchain integrations should use documented provider APIs, workflow
+surfaces, package-registry flows, cloud APIs, OIDC, and least-privilege
+credentials. They should not bypass provider protections, hide credential
+boundaries, or forge release evidence.
+
+See [PROVIDER_COMPLIANCE.md](PROVIDER_COMPLIANCE.md) for the official provider
+integration posture.
+
 ## Third-party software
 
 Buildchain depends on third-party software. Source dependencies are declared in

package/README.md

@@ -85,6 +85,19 @@ const report = verifyBuildchainLogEvents({
 The package also ships `dist/site/` as the Buildchain-owned fact source for
 `buildchain.libkungfu.dev`.
 
+## Project Governance
+
+- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project
+  license, DCO-based contributions, and third-party notice boundary.
+- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork
+  identity boundaries.
+- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official
+  services and maintainer-operated infrastructure.
+- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official
+  posture for GitHub, npm, cloud, credential, release evidence, and other
+  provider integrations.
+- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.
+
 Native build consumers can import the diagnostics toolkit instead of copying
 repository-local probes:
 

package/SECURITY.md

@@ -35,6 +35,13 @@ Security reports may cover:
 - local file access, path traversal, or unsafe archive handling;
 - credential, token, or private data exposure.
 
+Service-abuse, provider-compliance, credential-handling, misleading official
+identity, or compromised release-evidence reports may also be
+security-sensitive. Use private vulnerability reporting when public disclosure
+would expose credentials, provider account details, user data, or an exploitable
+bypass. See `ACCEPTABLE_USE.md`, `PROVIDER_COMPLIANCE.md`, and `TRADEMARK.md`
+for the related policy boundaries.
+
 ## Public disclosure
 
 Please allow maintainers time to investigate and prepare a fix before public

package/docs/MAP.md

@@ -43,6 +43,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
 | What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md) | verify | stable |
 | What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |
+| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |
 | How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |
 
 ## Also asking about
@@ -88,6 +89,10 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`site-bundle-contract.md`](site-bundle-contract.md).
 - **sites / web previews / staging / production gates** ->
   [`web-surface-deployments.md`](web-surface-deployments.md).
+- **trademark / fork / official service / provider compliance / release
+  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),
+  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and
+  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).
 
 ## How this map is maintained
 

package/docs/release-candidate.md

@@ -64,4 +64,15 @@ Buildchain-owned promotion workflow resolves the matching same-repository
 merged channel PR and downloads its PR-stage RC passport automatically before
 promotion starts. The consumer wrapper defaults to a PR-stage workflow file
 named `build.yml` with display name `Build`, and filters the RC passport and
-build summary by the configured `artifact-name` before promotion.
+build summary by the configured `artifact-name` before promotion. It also
+downloads payload artifacts from the same PR-stage run, validates the required
+payload count, passes downloaded platform manifests into the release passport,
+and either forwards an explicit `publish-required-artifacts-json` value or
+generates one before calling `promote-buildchain-ref`. The default npm path
+generates that requirement list from the downloaded `.tgz` payloads themselves:
+Buildchain reads `package/package.json` inside each tarball for the real scoped
+package name and version, computes npm-style `sha512-...` integrity over the
+tarball bytes, marks `publish-package-main` as `role: main`, and marks every
+other package as `role: platform`. Consumer workflows therefore stay
+declarative and do not need their own artifact download or publish-evidence
+generation scripts.

package/docs/reusable-build-surface.md

@@ -377,12 +377,14 @@ The passport records two separate source identities:
   commit used for publish authority.
 
 The reusable promote wrapper resolves the merged PR, finds exactly one matching
-PR-stage release-candidate artifact, downloads it, compares the built tree with
-the promotion channel tree, locks `publish-gate/{alpha,release,major}` to the
-promotion channel commit, and then calls `actions/promote-buildchain-ref` with
+PR-stage release-candidate artifact, downloads it with the build summary and
+payload artifacts from the same PR-stage run, validates the payload count,
+compares the built tree with the promotion channel tree, locks
+`publish-gate/{alpha,release,major}` to the promotion channel commit, and then
+calls `actions/promote-buildchain-ref` with
 `promote-only-release-candidate: "true"`. It does not call `.build.yml`, does
-not create a matrix, and must fail before publish if the RC evidence is missing
-or ambiguous.
+not create a matrix, and must fail before publish if the RC evidence or payload
+set is missing or ambiguous.
 
 ```yaml
 jobs:
@@ -400,8 +402,26 @@ jobs:
       publish-target: npm
       runner-preset: github-hosted
       trusted-publishing: true
+      required-status-check: check
+      required-artifact-count: 3
+      publish-dist-tag: alpha
+      publish-package-set-order: platforms-first-main-last
+      publish-package-main: "@kungfu-tech/libnode"
+      release-passport-product-name: Libnode
 ```
 
+`publish-required-artifacts-json` can still be passed explicitly for custom
+publish targets. For the default `publish-artifact-kind: npm` path, consumers do
+not download artifacts or run repository scripts to build publish evidence. The
+wrapper downloads the PR-stage payload artifacts, finds the downloaded `.tgz`
+packages, reads each tarball's `package/package.json` for the real scoped
+package name and version, computes the npm `sha512-...` integrity from the
+tarball bytes, marks the package matching `publish-package-main` as `role:
+main`, marks the rest as `role: platform`, and passes the generated
+`publish-required-artifacts-json` to `promote-buildchain-ref` before any publish
+side effect. Downloaded platform manifests are still passed into the release
+passport unless `release-passport-platform-manifest-paths` is set explicitly.
+
 Custom publish jobs can also repeat the channel-ref preflight:
 
 ```yaml

package/package.json

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

package/scripts/release-candidate-resolver.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -118,6 +119,173 @@ function outputPath(filePath) {
   return relative.startsWith("../") || relative === ".." ? filePath : relative;
 }
 
+function splitPatterns(value = "") {
+  return String(value || "")
+    .split(/\r?\n|,/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function artifactPatternToRegExp(pattern) {
+  return new RegExp(`^${String(pattern).split("*").map(escapeRegExp).join(".*")}$`);
+}
+
+export function selectPayloadArtifacts({
+  artifacts = [],
+  artifactName = "",
+  sourceSha = "",
+  patterns = [],
+} = {}) {
+  const prefix = String(artifactName || "").trim();
+  const sha = assertSha(sourceSha, "sourceSha");
+  const active = artifacts.filter((artifact) => !artifact.expired);
+  const excludedNames = new Set([
+    `${prefix}-release-candidate-${sha}`,
+    `${prefix}-summary-${sha}`,
+    `${prefix}-diagnostics-summary-${sha}`,
+  ]);
+  const effectivePatterns = splitPatterns(patterns).length
+    ? splitPatterns(patterns)
+    : [`${prefix}-manifest-*-${sha}`];
+  const matchers = effectivePatterns.map(artifactPatternToRegExp);
+  return active
+    .filter((artifact) => !excludedNames.has(String(artifact.name || "")))
+    .filter((artifact) => matchers.some((matcher) => matcher.test(String(artifact.name || ""))))
+    .sort((left, right) => String(left.name || "").localeCompare(String(right.name || "")));
+}
+
+function findDownloadedFiles(root, filename) {
+  const matches = [];
+  const stack = fs.existsSync(root) ? [root] : [];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.name === filename) {
+        matches.push(fullPath);
+      }
+    }
+  }
+  return matches.sort();
+}
+
+function findDownloadedFilesByExtension(root, extensions = []) {
+  const normalizedExtensions = extensions.map((extension) => String(extension || "").toLowerCase());
+  const matches = [];
+  const stack = fs.existsSync(root) ? [root] : [];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      const lowerName = entry.name.toLowerCase();
+      if (normalizedExtensions.some((extension) => lowerName.endsWith(extension))) {
+        matches.push(fullPath);
+      }
+    }
+  }
+  return matches.sort();
+}
+
+function packageNameFromArtifactPath(filePath) {
+  const basename = path.basename(String(filePath || ""));
+  return basename
+    .replace(/\.tgz$/i, "")
+    .replace(/\.tar\.gz$/i, "")
+    .replace(/\.zip$/i, "");
+}
+
+function npmIntegrity(filePath) {
+  return `sha512-${crypto.createHash("sha512").update(fs.readFileSync(filePath)).digest("base64")}`;
+}
+
+function readNpmPackageJsonFromTarball(tarballPath) {
+  const candidates = ["package/package.json", "./package/package.json"];
+  const errors = [];
+  for (const candidate of candidates) {
+    try {
+      return JSON.parse(execFileSync("tar", ["-xOf", tarballPath, candidate], { encoding: "utf8" }));
+    } catch (error) {
+      errors.push(error.stderr?.toString?.().trim() || error.message);
+    }
+  }
+  throw new Error(`npm package tarball ${tarballPath} does not contain package/package.json: ${errors.filter(Boolean).join("; ")}`);
+}
+
+export function readNpmPackageArtifact({
+  tarballPath,
+  mainPackage = "",
+  kind = "npm",
+} = {}) {
+  const packageJson = readNpmPackageJsonFromTarball(tarballPath);
+  const name = String(packageJson.name || "").trim();
+  const version = String(packageJson.version || "").trim();
+  if (!name || !version) {
+    throw new Error(`npm package tarball ${tarballPath || "<empty>"} package.json must include name and version`);
+  }
+  const integrity = npmIntegrity(tarballPath);
+  return {
+    kind,
+    name,
+    ref: version,
+    digest: integrity,
+    integrity,
+    role: mainPackage && name === mainPackage ? "main" : "platform",
+  };
+}
+
+export function generatePublishRequiredArtifacts({
+  manifests = [],
+  version = "",
+  kind = "npm",
+  tarballPaths = [],
+  mainPackage = "",
+} = {}) {
+  if (String(kind || "") === "npm" && tarballPaths.length > 0) {
+    const artifacts = tarballPaths
+      .map((tarballPath) => readNpmPackageArtifact({ tarballPath, mainPackage, kind }))
+      .sort((left, right) => `${left.role}:${left.name}`.localeCompare(`${right.role}:${right.name}`));
+    const seen = new Set();
+    for (const artifact of artifacts) {
+      const key = `${artifact.name}@${artifact.ref}`;
+      if (seen.has(key)) {
+        throw new Error(`duplicate npm package tarball for ${key}`);
+      }
+      seen.add(key);
+    }
+    return artifacts;
+  }
+  const ref = String(version || "").trim();
+  if (!ref) {
+    return [];
+  }
+  return manifests.flatMap((manifest) => {
+    const platform = manifest.platform?.id || manifest.platformId || "";
+    const files = Array.isArray(manifest.files) ? manifest.files : [];
+    return files
+      .filter((file) => file?.sha256)
+      .map((file) => ({
+        kind,
+        name: packageNameFromArtifactPath(file.path || file.name || manifest.artifactName || platform),
+        ref,
+        digest: String(file.sha256).startsWith("sha256:")
+          ? String(file.sha256)
+          : `sha256:${file.sha256}`,
+        role: "platform",
+        platform,
+      }));
+  });
+}
+
 export function selectReleaseCandidateArtifacts({ artifacts = [], artifactName = "" }) {
   const expectedPrefix = String(artifactName || "").trim();
   const active = artifacts.filter((artifact) => !artifact.expired);
@@ -170,6 +338,10 @@ export async function resolveReleaseCandidateArtifacts({
   workflowFile = DEFAULT_WORKFLOW_FILE,
   workflowName = "Build Surface Fixture",
   artifactName = "",
+  artifactPatterns = "",
+  requiredArtifactCount = 0,
+  publishArtifactKind = "npm",
+  publishPackageMain = "",
   outputDir = ".buildchain/release-candidate",
   fetchImpl = globalThis.fetch,
   download = true,
@@ -221,6 +393,16 @@ export async function resolveReleaseCandidateArtifacts({
     artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
     artifactName,
   });
+  const payloadArtifacts = selectPayloadArtifacts({
+    artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
+    artifactName: selected.prefix,
+    sourceSha: selected.sourceSha,
+    patterns: artifactPatterns,
+  });
+  const minimumPayloadCount = Number(requiredArtifactCount || 0);
+  if (minimumPayloadCount > 0 && payloadArtifacts.length < minimumPayloadCount) {
+    throw new Error(`expected at least ${minimumPayloadCount} PR-stage payload artifacts, found ${payloadArtifacts.length}`);
+  }
   const result = {
     enabled: true,
     repository: repoInfo.fullName,
@@ -240,6 +422,7 @@ export async function resolveReleaseCandidateArtifacts({
     artifacts: {
       passport: selected.passport.name,
       summary: selected.summary.name,
+      payloads: payloadArtifacts.map((artifact) => artifact.name),
       artifactName: selected.prefix,
       sourceSha: selected.sourceSha,
     },
@@ -252,6 +435,7 @@ export async function resolveReleaseCandidateArtifacts({
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-rc-"));
   const passportDir = path.join(resolvedOutput, "passport");
   const summaryDir = path.join(resolvedOutput, "summary");
+  const payloadDir = path.join(resolvedOutput, "payloads");
   const passportZip = path.join(tempDir, "passport.zip");
   const summaryZip = path.join(tempDir, "summary.zip");
   await githubDownload({
@@ -268,6 +452,18 @@ export async function resolveReleaseCandidateArtifacts({
     outputPath: summaryZip,
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/artifacts/${selected.summary.id}/zip`,
   });
+  for (const artifact of payloadArtifacts) {
+    const safeName = String(artifact.name || `artifact-${artifact.id}`).replace(/[^A-Za-z0-9._-]/g, "_");
+    const payloadZip = path.join(tempDir, `${safeName}.zip`);
+    await githubDownload({
+      apiUrl,
+      token,
+      fetchImpl,
+      outputPath: payloadZip,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/artifacts/${artifact.id}/zip`,
+    });
+    unzip(payloadZip, path.join(payloadDir, safeName));
+  }
   unzip(passportZip, passportDir);
   unzip(summaryZip, summaryDir);
   fs.rmSync(tempDir, { recursive: true, force: true });
@@ -277,14 +473,43 @@ export async function resolveReleaseCandidateArtifacts({
     throw new Error("downloaded release-candidate artifacts did not contain release-candidate-passport.json and build-summary.json");
   }
   const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
+  const platformManifestPaths = findDownloadedFiles(payloadDir, "manifest.json");
+  const npmTarballPaths = publishArtifactKind === "npm"
+    ? findDownloadedFilesByExtension(payloadDir, [".tgz"])
+    : [];
+  const downloadedRequiredArtifactCount = publishArtifactKind === "npm"
+    ? npmTarballPaths.length
+    : platformManifestPaths.length;
+  if (minimumPayloadCount > 0 && downloadedRequiredArtifactCount < minimumPayloadCount) {
+    const noun = publishArtifactKind === "npm" ? "npm package tarballs" : "platform manifests";
+    throw new Error(`expected at least ${minimumPayloadCount} downloaded ${noun}, found ${downloadedRequiredArtifactCount}`);
+  }
+  const manifests = platformManifestPaths.map((manifestPath) => JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+  const generatedRequiredArtifacts = generatePublishRequiredArtifacts({
+    manifests,
+    version: passport.target?.version || "",
+    kind: publishArtifactKind,
+    tarballPaths: npmTarballPaths,
+    mainPackage: publishPackageMain,
+  });
+  const requiredArtifactsPath = path.join(resolvedOutput, "publish-required-artifacts.json");
+  fs.writeFileSync(requiredArtifactsPath, `${JSON.stringify(generatedRequiredArtifacts, null, 2)}\n`);
   return {
     ...result,
     paths: {
       passport: outputPath(passportPath),
       buildSummary: outputPath(buildSummaryPath),
+      payloads: outputPath(payloadDir),
+      platformManifests: platformManifestPaths.map(outputPath),
+      npmTarballs: npmTarballPaths.map(outputPath),
+      publishRequiredArtifacts: outputPath(requiredArtifactsPath),
     },
     version: passport.target?.version || "",
     candidateHash: passport.candidateHash || "",
+    payloadCount: payloadArtifacts.length,
+    platformManifestCount: platformManifestPaths.length,
+    npmTarballCount: npmTarballPaths.length,
+    publishRequiredArtifacts: generatedRequiredArtifacts,
   };
 }
 
@@ -296,6 +521,10 @@ export async function resolveReleaseCandidateArtifactsCli() {
     workflowFile: env("BUILDCHAIN_RC_WORKFLOW_FILE", DEFAULT_WORKFLOW_FILE),
     workflowName: env("BUILDCHAIN_RC_WORKFLOW_NAME", ""),
     artifactName: env("BUILDCHAIN_ARTIFACT_NAME"),
+    artifactPatterns: env("BUILDCHAIN_ARTIFACT_PATTERNS"),
+    requiredArtifactCount: env("BUILDCHAIN_REQUIRED_ARTIFACT_COUNT", "0"),
+    publishArtifactKind: env("BUILDCHAIN_PUBLISH_ARTIFACT_KIND", "npm"),
+    publishPackageMain: env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN"),
     outputDir: env("BUILDCHAIN_RC_OUTPUT_DIR", ".buildchain/release-candidate"),
   });
   writeGitHubOutputs({
@@ -306,6 +535,14 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",
     "release-candidate-build-summary-artifact": result.artifacts?.summary || "",
+    "release-candidate-payload-artifacts": (result.artifacts?.payloads || []).join(","),
+    "release-candidate-payload-dir": result.paths?.payloads || "",
+    "release-candidate-platform-manifest-paths": (result.paths?.platformManifests || []).join(","),
+    "release-candidate-platform-manifest-count": String(result.platformManifestCount || 0),
+    "release-candidate-npm-tarball-paths": (result.paths?.npmTarballs || []).join(","),
+    "release-candidate-npm-tarball-count": String(result.npmTarballCount || 0),
+    "publish-required-artifacts-json": JSON.stringify(result.publishRequiredArtifacts || []),
+    "publish-required-artifacts-path": result.paths?.publishRequiredArtifacts || "",
     "release-candidate-run-id": result.run?.id || "",
     "release-candidate-run-url": result.run?.url || "",
     "release-candidate-pr": result.pullRequest?.number ? String(result.pullRequest.number) : "",