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

package/packages/core/publication-control-plane-audit.js

@@ -10,6 +10,34 @@ export const BUILDCHAIN_RELEASE_RECONCILIATION_PATHS = Object.freeze([
   "package.json",
 ]);
 
+function deploymentPatternExpression(pattern) {
+  let expression = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === "*") {
+      if (pattern[index + 1] === "*") {
+        expression += ".*";
+        index += 1;
+      } else {
+        expression += "[^/]*";
+      }
+    } else {
+      expression += character.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${expression}$`);
+}
+
+export function matchesGithubDeploymentPolicy(policy, { ref, refType = "branch" } = {}) {
+  const normalizedRef = String(ref || "");
+  const normalizedType = String(refType || "");
+  const policyName = String(policy?.name || "");
+  const policyType = String(policy?.type || "");
+  if (!normalizedRef || !["branch", "tag"].includes(normalizedType)) return false;
+  if (policyType !== normalizedType || !policyName) return false;
+  return deploymentPatternExpression(policyName).test(normalizedRef);
+}
+
 export function evaluateBuildchainReleaseReconciliation({
   repository,
   publicationVersion,

package/packages/core/release-passport.js

@@ -2428,41 +2428,50 @@ export function createReleaseCheckReport({
   };
 }
 
-export async function readJsonFromLocation(location, redirectCount = 0) {
+export async function readJsonFromLocation(
+  location,
+  redirectCount = 0,
+  { timeoutMs = 15_000 } = {},
+) {
   const input = nonEmptyString(location, "location");
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("timeoutMs must be a positive integer");
+  }
   if (redirectCount > 5) {
     throw new Error(`too many redirects while reading ${input}`);
   }
   if (/^https?:\/\//.test(input)) {
     const client = input.startsWith("https:") ? https : http;
     return new Promise((resolve, reject) => {
-      client
-        .get(input, (response) => {
-          if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
-            const nextLocation = new URL(response.headers.location, input).toString();
-            response.resume();
-            readJsonFromLocation(nextLocation, redirectCount + 1).then(resolve, reject);
-            return;
-          }
-          if (response.statusCode < 200 || response.statusCode >= 300) {
-            reject(new Error(`HTTP ${response.statusCode} while reading ${input}`));
-            response.resume();
-            return;
+      const request = client.get(input, (response) => {
+        if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+          const nextLocation = new URL(response.headers.location, input).toString();
+          response.resume();
+          readJsonFromLocation(nextLocation, redirectCount + 1, { timeoutMs }).then(resolve, reject);
+          return;
+        }
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`HTTP ${response.statusCode} while reading ${input}`));
+          response.resume();
+          return;
+        }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch (error) {
+            reject(error);
           }
-          let body = "";
-          response.setEncoding("utf8");
-          response.on("data", (chunk) => {
-            body += chunk;
-          });
-          response.on("end", () => {
-            try {
-              resolve(JSON.parse(body));
-            } catch (error) {
-              reject(error);
-            }
-          });
-        })
-        .on("error", reject);
+        });
+      });
+      request.setTimeout(timeoutMs, () => {
+        request.destroy(new Error(`timed out after ${timeoutMs}ms while reading ${input}`));
+      });
+      request.on("error", reject);
     });
   }
   return readJsonFile(input);

package/packages/core/stable-release-gate.js

@@ -194,12 +194,14 @@ export function evaluateStableReleaseGate({
       : undefined;
     const attestorAllowed = required.allowedAttestors.length === 0 ||
       required.allowedAttestors.includes(string(evidence?.attestor));
+    const completionTimingValid = required.source === "release-candidate" ||
+      (completedAt && completedAt.milliseconds >= candidatePublished.milliseconds);
     const valid = Boolean(
       evidence &&
       string(evidence.status) === "success" &&
       string(evidence.candidateSha) === candidateSha &&
       completedAt &&
-      completedAt.milliseconds >= candidatePublished.milliseconds &&
+      completionTimingValid &&
       attestorAllowed,
     );
     if (completedAt) {
@@ -222,6 +224,7 @@ export function evaluateStableReleaseGate({
         evidenceUrl: string(evidence?.evidenceUrl),
         attestor: string(evidence?.attestor),
         attestorAllowed,
+        completionTimingValid: Boolean(completionTimingValid),
       },
     ));
   }

package/scripts/artifact-signing-delegation.mjs

@@ -0,0 +1,268 @@
+#!/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";
+
+const CONTRACT = "kungfu-buildchain-artifact-signing-delegation/v1";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  if (/[\r\n\0]/u.test(normalized))
+    throw new Error(`${label} contains control characters`);
+  return normalized;
+}
+
+function optional(value, label) {
+  const normalized = String(value || "").trim();
+  if (/[\r\n\0]/u.test(normalized))
+    throw new Error(`${label} contains control characters`);
+  return normalized;
+}
+
+function exactSha(value, label) {
+  const normalized = required(value, label);
+  if (!/^[0-9a-f]{40}$/u.test(normalized))
+    throw new Error(`${label} must be an exact SHA`);
+  return normalized;
+}
+
+function positiveInteger(value, label, { allowZero = false } = {}) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < (allowZero ? 0 : 1)) {
+    throw new Error(
+      `${label} must be ${allowZero ? "a non-negative" : "a positive"} integer`,
+    );
+  }
+  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;
+}
+
+function safeRelativePath(value, label) {
+  const normalized = required(value, label).replaceAll("\\", "/");
+  const resolved = path.posix.normalize(normalized);
+  if (
+    resolved === ".." ||
+    resolved.startsWith("../") ||
+    path.posix.isAbsolute(resolved)
+  ) {
+    throw new Error(`${label} must be a safe relative path`);
+  }
+  if (!/^[A-Za-z0-9._ /-]+$/u.test(resolved))
+    throw new Error(`${label} contains unsafe shell characters`);
+  return resolved;
+}
+
+export function validateArtifactSigningDelegation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("delegation must be an object");
+  if (value.schemaVersion !== 1 || value.contract !== CONTRACT)
+    throw new Error("artifact signing delegation contract mismatch");
+  const requestCount = positiveInteger(value.request?.count, "request.count", {
+    allowZero: true,
+  });
+  const delegation = {
+    schemaVersion: 1,
+    contract: CONTRACT,
+    source: {
+      repository: repository(value.source?.repository, "source.repository"),
+      runId: required(value.source?.runId, "source.runId"),
+      runAttempt: positiveInteger(
+        value.source?.runAttempt,
+        "source.runAttempt",
+      ),
+      sha: exactSha(value.source?.sha, "source.sha"),
+      treeSha: exactSha(value.source?.treeSha, "source.treeSha"),
+    },
+    runtime: {
+      repository: repository(value.runtime?.repository, "runtime.repository"),
+      sha: exactSha(value.runtime?.sha, "runtime.sha"),
+    },
+    platform: {
+      id: required(value.platform?.id, "platform.id"),
+      name: required(value.platform?.name, "platform.name"),
+    },
+    request: {
+      count: requestCount,
+      artifact:
+        requestCount > 0
+          ? required(value.request?.artifact, "request.artifact")
+          : optional(value.request?.artifact, "request.artifact"),
+    },
+    authority: {
+      runId:
+        requestCount > 0
+          ? required(value.authority?.runId, "authority.runId")
+          : optional(value.authority?.runId, "authority.runId"),
+      resultArtifact:
+        requestCount > 0
+          ? required(
+              value.authority?.resultArtifact,
+              "authority.resultArtifact",
+            )
+          : optional(
+              value.authority?.resultArtifact,
+              "authority.resultArtifact",
+            ),
+    },
+    artifact: {
+      name: required(value.artifact?.name, "artifact.name"),
+      manifestArtifact: required(
+        value.artifact?.manifestArtifact,
+        "artifact.manifestArtifact",
+      ),
+      diagnosticsArtifact: required(
+        value.artifact?.diagnosticsArtifact,
+        "artifact.diagnosticsArtifact",
+      ),
+    },
+    workingDirectory: safeRelativePath(
+      value.workingDirectory || ".",
+      "workingDirectory",
+    ),
+  };
+  if (
+    requestCount === 0 &&
+    (delegation.authority.runId || delegation.authority.resultArtifact)
+  ) {
+    throw new Error(
+      "unsigned delegation must not contain authority result coordinates",
+    );
+  }
+  return delegation;
+}
+
+export function createArtifactSigningDelegation({
+  sourceRepository = process.env.GITHUB_REPOSITORY,
+  sourceRunId = process.env.GITHUB_RUN_ID,
+  sourceRunAttempt = process.env.GITHUB_RUN_ATTEMPT || "1",
+  sourceSha = process.env.BUILDCHAIN_SOURCE_SHA,
+  sourceTreeSha = process.env.BUILDCHAIN_SOURCE_TREE_SHA,
+  runtimeRepository = process.env.BUILDCHAIN_RUNTIME_REPOSITORY,
+  runtimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
+  platformId = process.env.BUILDCHAIN_PLATFORM_ID,
+  platformName = process.env.BUILDCHAIN_PLATFORM_NAME,
+  requestCount = process.env.BUILDCHAIN_SIGNING_REQUEST_COUNT || "0",
+  requestArtifact = process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT || "",
+  authorityRunId = process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  resultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT || "",
+  artifactName = process.env.BUILDCHAIN_ARTIFACT_NAME,
+  manifestArtifact = process.env.BUILDCHAIN_MANIFEST_ARTIFACT_NAME,
+  diagnosticsArtifact = process.env.BUILDCHAIN_DIAGNOSTICS_ARTIFACT_NAME,
+  workingDirectory = process.env.BUILDCHAIN_SIGNING_CWD || ".",
+} = {}) {
+  return validateArtifactSigningDelegation({
+    schemaVersion: 1,
+    contract: CONTRACT,
+    source: {
+      repository: sourceRepository,
+      runId: sourceRunId,
+      runAttempt: Number(sourceRunAttempt),
+      sha: sourceSha,
+      treeSha: sourceTreeSha,
+    },
+    runtime: { repository: runtimeRepository, sha: runtimeSha },
+    platform: { id: platformId, name: platformName },
+    request: { count: Number(requestCount), artifact: requestArtifact },
+    authority: { runId: authorityRunId, resultArtifact },
+    artifact: { name: artifactName, manifestArtifact, diagnosticsArtifact },
+    workingDirectory,
+  });
+}
+
+export function sealArtifactSigningDelegation({
+  outputPath = process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+  ...values
+} = {}) {
+  const delegation = createArtifactSigningDelegation(values);
+  const target = path.resolve(required(outputPath, "delegation output path"));
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(delegation, null, 2)}\n`);
+  return delegation;
+}
+
+export function readArtifactSigningDelegation(
+  inputPath = process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+) {
+  const target = path.resolve(required(inputPath, "delegation input path"));
+  return validateArtifactSigningDelegation(
+    JSON.parse(fs.readFileSync(target, "utf8")),
+  );
+}
+
+export function artifactSigningDelegationOutputs(delegation) {
+  const value = validateArtifactSigningDelegation(delegation);
+  return {
+    "request-count": String(value.request.count),
+    "request-artifact": value.request.artifact,
+    "authority-run-id": value.authority.runId,
+    "result-artifact": value.authority.resultArtifact,
+    "artifact-name": value.artifact.name,
+    "manifest-artifact-name": value.artifact.manifestArtifact,
+    "diagnostics-artifact-name": value.artifact.diagnosticsArtifact,
+    "working-directory": value.workingDirectory,
+  };
+}
+
+export function assertArtifactSigningDelegationContext(
+  delegation,
+  {
+    sourceRepository = process.env.BUILDCHAIN_EXPECTED_SOURCE_REPOSITORY || "",
+    sourceRunId = process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ID || "",
+    sourceRunAttempt = process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ATTEMPT || "",
+    sourceSha = process.env.BUILDCHAIN_EXPECTED_SOURCE_SHA || "",
+    runtimeRepository = process.env.BUILDCHAIN_EXPECTED_RUNTIME_REPOSITORY ||
+      "",
+    runtimeSha = process.env.BUILDCHAIN_EXPECTED_RUNTIME_SHA || "",
+    platformId = process.env.BUILDCHAIN_EXPECTED_PLATFORM_ID || "",
+  } = {},
+) {
+  const value = validateArtifactSigningDelegation(delegation);
+  const expectations = [
+    [sourceRepository, value.source.repository, "source repository"],
+    [sourceRunId, value.source.runId, "source run ID"],
+    [sourceRunAttempt, String(value.source.runAttempt), "source run attempt"],
+    [sourceSha, value.source.sha, "source SHA"],
+    [runtimeRepository, value.runtime.repository, "runtime repository"],
+    [runtimeSha, value.runtime.sha, "runtime SHA"],
+    [platformId, value.platform.id, "platform ID"],
+  ];
+  for (const [expected, actual, label] of expectations) {
+    if (expected && String(expected) !== actual)
+      throw new Error(`artifact signing delegation ${label} mismatch`);
+  }
+  return value;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const mode = process.argv[2] || "seal";
+    if (mode === "seal") {
+      sealArtifactSigningDelegation();
+    } else if (mode === "outputs") {
+      const delegation = assertArtifactSigningDelegationContext(
+        readArtifactSigningDelegation(),
+      );
+      writeGitHubOutputs(artifactSigningDelegationOutputs(delegation));
+    } else {
+      throw new Error(`unsupported artifact signing delegation mode: ${mode}`);
+    }
+  } catch (error) {
+    console.error(
+      `::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/audit-github-governance.mjs

@@ -254,15 +254,33 @@ function addMinutes(iso, minutes) {
   return new Date(Date.parse(iso) + minutes * 60_000).toISOString();
 }
 
-function repositorySelector(repositories, requested) {
-  if (!requested) return repositories;
-  const exact = repositories.filter((repository) =>
-    repository.full_name === requested ||
-    repository.name === requested);
-  if (exact.length !== 1) {
-    throw new Error(`repository selector must resolve exactly once: ${requested}`);
+function repositoryVisibility(repository) {
+  return String(
+    repository.visibility || (repository.private ? "private" : "public"),
+  ).toLowerCase();
+}
+
+export function selectGithubGovernanceRepositories(
+  repositories,
+  requested = "",
+  descriptor = BUILDCHAIN_GITHUB_GOVERNANCE_AUTHORITY,
+) {
+  const exact = requested
+    ? repositories.filter((repository) =>
+        repository.full_name === requested || repository.name === requested)
+    : repositories;
+  if (requested && exact.length !== 1) {
+    throw new Error("repository selector must resolve exactly once");
   }
-  return exact;
+  const managedVisibilities = new Set(
+    descriptor.repositoryAdmission.managedVisibilities || ["public"],
+  );
+  const selected = exact.filter((repository) =>
+    managedVisibilities.has(repositoryVisibility(repository)));
+  if (requested && selected.length !== 1) {
+    throw new Error("repository selector is outside managed governance scope");
+  }
+  return selected;
 }
 
 export function collectGithubGovernanceAudit({
@@ -291,7 +309,10 @@ export function collectGithubGovernanceAudit({
   if (!organizationState.ok || !repositoriesState.readable) {
     throw new Error("organization or managed repository inventory is unreadable; governance audit fails closed");
   }
-  const selected = repositorySelector(repositoriesState.repositories, repository);
+  const selected = selectGithubGovernanceRepositories(
+    repositoriesState.repositories,
+    repository,
+  );
   if (targetRef && selected.length !== 1) {
     throw new Error("--target-ref requires exactly one selected repository");
   }
@@ -316,9 +337,7 @@ export function collectGithubGovernanceAudit({
   const diagnostics = [];
   for (const metadata of selected) {
     const fullName = String(metadata.full_name || "");
-    const visibilityClass = String(
-      metadata.visibility || (metadata.private ? "private" : "public"),
-    );
+    const visibilityClass = repositoryVisibility(metadata);
     const repositoryIdentityRoot = githubRepositoryIdentityRoot({
       provider: "github",
       providerRepositoryId: String(metadata.node_id || metadata.id || ""),
@@ -420,7 +439,7 @@ export function collectGithubGovernanceAudit({
     }
   }
   const visibility = selected.reduce((counts, item) => {
-    const key = String(item.visibility || (item.private ? "private" : "public"));
+    const key = repositoryVisibility(item);
     counts[key] = Number(counts[key] || 0) + 1;
     return counts;
   }, {});

package/scripts/audit-publication-control-plane.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import {
   evaluateBuildchainReleaseReconciliation,
   evaluatePublicationControlPlaneSnapshot,
+  matchesGithubDeploymentPolicy,
 } from "../packages/core/publication-control-plane-audit.js";
 
 function flag(name, fallback = "") {
@@ -197,8 +198,10 @@ function main() {
   const requiredStatusCheck = flag("required-status-check", "check");
   const jobId = flag("job", "promote");
   const environment = flag("environment", "none");
-  const providerEnvironment = environment === "none" ? "" : environment;
   const branch = flag("branch");
+  const environmentRef = flag("environment-ref", branch);
+  const environmentRefType = flag("environment-ref-type", "branch");
+  const providerEnvironment = environment === "none" ? "" : environment;
   const sourceSha = flag("source-sha").toLowerCase();
   const packageName = flag("package", "@kungfu-tech/buildchain");
   const publisherMode = flag("publisher-mode", "npm-trusted-publisher");
@@ -239,15 +242,19 @@ function main() {
   const deploymentBranches = environment !== "none" && environmentState.deployment_branch_policy?.custom_branch_policies === true
     ? githubJson(`repos/${repository}/environments/${encodeURIComponent(environment)}/deployment-branch-policies?per_page=100`, "Environment deployment branch policy")
     : { branch_policies: [] };
-  const exactEnvironmentBranchPolicy = (deploymentBranches.branch_policies || []).find((entry) =>
-    entry?.type === "branch" && entry?.name === branch
+  if (!["branch", "tag"].includes(environmentRefType)) {
+    throw new Error(`unsupported --environment-ref-type: ${environmentRefType}`);
+  }
+  const matchingEnvironmentPolicy = (deploymentBranches.branch_policies || []).find((entry) =>
+    matchesGithubDeploymentPolicy(entry, { ref: environmentRef, refType: environmentRefType })
   );
   const environmentBranchAuthorized = environment !== "none" && (
     (
+      environmentRefType === "branch" &&
       environmentState.deployment_branch_policy?.protected_branches === true &&
       branchState.protected === true
     ) ||
-    Boolean(exactEnvironmentBranchPolicy)
+    Boolean(matchingEnvironmentPolicy)
   );
   const oidc = githubJson(`repos/${repository}/actions/oidc/customization/sub`, "OIDC subject policy");
   if (!["npm-trusted-publisher", "github-token", "oidc-role"].includes(publisherMode)) {
@@ -465,12 +472,14 @@ function main() {
           environmentState.deployment_branch_policy?.protected_branches === true ||
           (deploymentBranches.branch_policies || []).length > 0,
         branchAuthorized: environmentBranchAuthorized,
-        branchPolicyMode: environmentState.deployment_branch_policy?.protected_branches === true
+        branchPolicyMode: environmentRefType === "branch" && environmentState.deployment_branch_policy?.protected_branches === true
           ? "protected-branches"
-          : exactEnvironmentBranchPolicy
-            ? "exact-custom-branch"
+          : matchingEnvironmentPolicy
+            ? `custom-${environmentRefType}-policy`
             : "unqualified",
-        authorizedBranch: exactEnvironmentBranchPolicy?.name || "",
+        authorizedBranch: matchingEnvironmentPolicy?.name || "",
+        authorizedRef: environmentRef,
+        authorizedRefType: environmentRefType,
         reviewRequired: reviewRules.length > 0,
         preventSelfReview: reviewRules.some((rule) => rule.prevent_self_review === true),
       },