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

package/packages/core/github-governance-authority.js

@@ -49,6 +49,7 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
     target("dev/v3/v3.0", [check("check")], false),
     target("alpha/v3/v3.0", [check("check"), check("verify")], false),
     target("release/v3/v3.0", [check("check")], true),
+    target("authority/v3/v3.0/artifact-signing", [check("check"), check("verify")], true),
     target("publish-gate/major", [check("check")], true),
   ],
   "homebrew-tap": [
@@ -65,6 +66,11 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
       check("signoff"),
       check("validate"),
     ], true),
+    target("release/v4/v4.0", [
+      check("build", null),
+      check("signoff"),
+      check("validate"),
+    ], true),
   ],
   libnode: [
     target("dev/v22/v22.22", [check("build")], true),
@@ -1191,20 +1197,38 @@ export function createGithubRulesetGovernanceRolloutPlan({
   repository,
   targetRef,
   rulesetId,
+  rulesetName,
   inventory,
   rollbackSnapshot,
   desiredProtection,
 } = {}) {
   const fullName = requiredString(repository, "repository");
   const branch = normalizedRef(targetRef);
-  const id = Number(rulesetId);
-  if (!Number.isInteger(id) || id <= 0) {
-    throw new Error("ruleset id must be a positive integer");
+  const creating = rulesetId === null || rulesetId === undefined || rulesetId === "";
+  const id = creating ? null : Number(rulesetId);
+  if (!creating && (!Number.isInteger(id) || id <= 0)) {
+    throw new Error("ruleset id must be a positive integer when supplied");
   }
-  if (!inventory || !rollbackSnapshot) {
-    throw new Error("read-only inventory and frozen rollback snapshot are required");
+  if (!inventory || (!creating && !rollbackSnapshot)) {
+    throw new Error(
+      "read-only inventory and any existing frozen rollback snapshot are required",
+    );
   }
-  const before = normalizeGithubRulesetSnapshot(rollbackSnapshot);
+  const before = creating
+    ? {
+        name: requiredString(rulesetName, "ruleset name"),
+        target: "branch",
+        enforcement: "active",
+        bypass_actors: [],
+        conditions: {
+          ref_name: {
+            include: [`refs/heads/${branch}`],
+            exclude: [],
+          },
+        },
+        rules: [],
+      }
+    : normalizeGithubRulesetSnapshot(rollbackSnapshot);
   const exactInclude = before.conditions?.ref_name?.include || [];
   const exactExclude = before.conditions?.ref_name?.exclude || [];
   if (
@@ -1265,28 +1289,53 @@ export function createGithubRulesetGovernanceRolloutPlan({
   });
   if (pullRequestRules.length === 0) desiredRules.push(desiredPullRequestRule);
   if (statusCheckRules.length === 0) desiredRules.push(desiredStatusCheckRule);
+  if (
+    desiredProtection?.blockDeletions === true &&
+    !desiredRules.some((rule) => rule.type === "deletion")
+  ) {
+    desiredRules.push({ type: "deletion" });
+  }
+  if (
+    desiredProtection?.blockNonFastForward === true &&
+    !desiredRules.some((rule) => rule.type === "non_fast_forward")
+  ) {
+    desiredRules.push({ type: "non_fast_forward" });
+  }
   const desired = {
     ...before,
+    name: rulesetName
+      ? requiredString(rulesetName, "ruleset name")
+      : before.name,
     bypass_actors: providerRulesetBypassActors(
       desiredProtection?.rulesetBypassActors,
     ),
     rules: desiredRules,
   };
-  const endpoint = `repos/${fullName}/rulesets/${id}`;
+  const endpoint = creating
+    ? `repos/${fullName}/rulesets`
+    : `repos/${fullName}/rulesets/${id}`;
   const core = {
     schemaVersion: 1,
     contract: GITHUB_GOVERNANCE_RULESET_ROLLOUT_CONTRACT,
     repository: fullName,
     targetRef: branch,
     rulesetId: id,
+    rulesetName: desired.name,
+    action: creating ? "create" : "update",
     inventoryRoot: githubGovernanceDigest(inventory),
-    rollbackSnapshotRoot: githubGovernanceDigest(before),
-    operations: [{ method: "PUT", endpoint, body: desired }],
+    rollbackSnapshotRoot: creating
+      ? githubGovernanceDigest({ rulesetExists: false, targetRef: branch })
+      : githubGovernanceDigest(before),
+    operations: [
+      { method: creating ? "POST" : "PUT", endpoint, body: desired },
+    ],
     impact: [
       "replace ruleset bypass actors with the exact provider-admitted desired set",
       "require fresh Code Owner review and resolved review threads",
       "bind required status checks and strictness to the authoritative target descriptor",
-      "preserve unrelated ruleset rules and exact target conditions",
+      creating
+        ? "create one exact-branch active ruleset because no matching ruleset exists"
+        : "preserve unrelated ruleset rules and exact target conditions",
     ],
     expectedObservation: {
       rulesetRoot: githubGovernanceDigest(desired),
@@ -1296,12 +1345,24 @@ export function createGithubRulesetGovernanceRolloutPlan({
         desiredProtection?.strictRequiredChecks === true,
       requiredApprovals,
     },
-    rollback: [{
-      method: "PUT",
-      endpoint,
-      body: before,
-      preconditionRoot: githubGovernanceDigest(before),
-    }],
+    rollback: creating
+      ? [
+          {
+            method: "DELETE",
+            endpoint: `repos/${fullName}/rulesets/{ruleset_id}`,
+            body: null,
+            preconditionRoot: githubGovernanceDigest(desired),
+            requiresApplyReceipt: true,
+          },
+        ]
+      : [
+          {
+            method: "PUT",
+            endpoint,
+            body: before,
+            preconditionRoot: githubGovernanceDigest(before),
+          },
+        ],
   };
   return { ...core, planRoot: githubGovernanceDigest(core) };
 }

package/packages/core/index.js

@@ -64,6 +64,16 @@ export {
   verifyPortableDevCachePlan,
 } from "./portable-dev-cache.js";
 
+export {
+  BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT,
+  BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT,
+  cacheEvidenceDigest,
+  createCacheEvidenceSet,
+  createCacheOperationReceipt,
+  verifyCacheEvidenceSet,
+  verifyCacheOperationReceipt,
+} from "./cache-evidence.js";
+
 export {
   explainReleaseLineDryRun,
   formatReleaseLineDryRun,
@@ -90,6 +100,12 @@ export {
   normalizeCandidateTimelineEvent,
 } from "./candidate-timeline.js";
 
+export {
+  CHANNEL_CANDIDATE_DECISION_SCHEMA,
+  channelCandidateSourceLockRef,
+  decideChannelCandidate,
+} from "./channel-candidate.js";
+
 export {
   BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT,
   BUILDCHAIN_DIAGNOSTICS_CONTRACT,
@@ -246,6 +262,33 @@ export {
   verifyArtifactVerificationEnvelope,
 } from "./artifact-verification-envelope.js";
 
+export {
+  ARTIFACT_SIGNING_AUTHORITY_CONTRACT,
+  ARTIFACT_SIGNING_RECEIPT_CONTRACT,
+  ARTIFACT_SIGNING_REQUEST_CONTRACT,
+  artifactSigningDigest,
+  createArtifactSigningReceipt,
+  createArtifactSigningRequest,
+  listArtifactSigningProfiles,
+  resolveArtifactSigningProfile,
+  validateArtifactSigningReceipt,
+  validateArtifactSigningRequest,
+} from "./artifact-signing.js";
+
+export {
+  ARTIFACT_SIGNING_RESULT_CONTRACT,
+  artifactSigningEvidenceDigest,
+  createArtifactSigningResult,
+  validateArtifactSigningResult,
+  verifyArtifactSigningResultFiles,
+} from "./artifact-signing-result.js";
+
+export {
+  DETACHED_ARTIFACT_SIGNATURE_CONTRACT,
+  signDetachedArtifactRequest,
+  verifyDetachedArtifactSignature,
+} from "./detached-artifact-signature.js";
+
 export {
   BUILDCHAIN_CONTRACT_LOCK,
   BUILDCHAIN_RUNTIME_CONTRACT_WORLD,
@@ -357,6 +400,25 @@ export {
   verifyReleasePassport,
 } from "./release-passport.js";
 
+export {
+  GITHUB_ARTIFACT_ATTESTATION_EVIDENCE_CONTRACT,
+  GITHUB_ARTIFACT_ATTESTATION_POLICY_CONTRACT,
+  GITHUB_ARTIFACT_ATTESTATION_PREDICATE_CONTRACT,
+  GITHUB_ARTIFACT_ATTESTATION_PREDICATE_TYPE,
+  GITHUB_ARTIFACT_ATTESTATION_VERIFICATION_CONTRACT,
+  GITHUB_ARTIFACT_ATTESTATION_WORKFLOW,
+  createGitHubArtifactAttestationEvidence,
+  createGitHubArtifactAttestationPolicy,
+  createGitHubArtifactAttestationVerificationPlan,
+  githubArtifactAttestationRequiredPermissions,
+  githubArtifactAttestationSemanticRoot,
+  githubArtifactAttestationSha256Buffer,
+  githubArtifactAttestationSha256File,
+  normalizeGitHubArtifactAttestationPolicy,
+  prepareGitHubArtifactAttestation,
+  verifyGitHubArtifactAttestationEvidence,
+} from "./github-artifact-attestation.js";
+
 export {
   KFD_AGENT_HUB_ADOPTION_CONTRACT,
   KFD_AGENT_HUB_ADOPTION_SCHEMA,

package/packages/core/publication-authority.js

@@ -106,7 +106,7 @@ export function detectPublicationAuthoritySignals(workflowText = "") {
   const signals = [];
   const rules = [
     ["write-all", /permissions\s*:\s*write-all|permissions\s*:\s*\{[^}]*write-all/i],
-    ["write-permission", /^\s*(?:contents|packages|deployments|checks|issues|pull-requests|actions)\s*:\s*write\s*$/im],
+    ["write-permission", /^\s*(?:contents|packages|deployments|checks|issues|pull-requests|actions|attestations|artifact-metadata)\s*:\s*write\s*$/im],
     ["oidc", /^\s*id-token\s*:\s*write\s*$/im],
     ["environment", /^\s*environment\s*:/im],
     ["npm-publish", /\bnpm\s+(?:stage\s+)?publish\b/i],

package/packages/core/release-passport-contract.js

@@ -96,6 +96,7 @@ export const RELEASE_PASSPORT_SCHEMA = {
     platformArtifactManifests: { type: "array", items: OBJECT },
     distTagPromotion: OBJECT,
     controllerReceipts: { type: "array", items: OBJECT },
+    githubArtifactAttestations: { type: "array", items: OBJECT },
     "kfd-1": OBJECT,
     "kfd-2": OBJECT,
     "kfd-3": OBJECT,
@@ -123,6 +124,7 @@ const BUILDCHAIN_AGGREGATION_FIELDS = [
   "distTagPromotion",
   "controllerReceipts",
   "kfdSupport",
+  "githubArtifactAttestations",
   "artifacts",
   "evidence",
   "recovery",

package/packages/core/release-passport.js

@@ -21,6 +21,9 @@ import {
 import { createSurfaceTimestampPolicy } from "./surface-manifest.js";
 import { validatePublishEvidence as validateTransactionPublishEvidence } from "./publish-transaction.js";
 import { normalizeControllerReceiptReferences } from "./controller-evidence.js";
+import {
+  normalizeGitHubArtifactAttestationPolicy,
+} from "./github-artifact-attestation.js";
 
 export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
 export const ARTIFACT_EVIDENCE_CONTRACT = "kungfu-buildchain-artifact-evidence";
@@ -1166,6 +1169,8 @@ export function createReleasePassport({
   kfdAgentHubEvidencePath = "",
   controllerReceipts = [],
   controllerReceiptReferences = [],
+  githubArtifactAttestations = [],
+  checkedAt = "",
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: normalizedTag, sourceSha, workflow });
@@ -1185,7 +1190,7 @@ export function createReleasePassport({
     ? normalizeEvidenceDocument(distTagPromotionEvidence, "distTagPromotionEvidence")
     : undefined;
   const normalizedImpact = normalizeImpactLedger(impact, { tag: normalizedTag, line });
-  const generatedAt = nowIso();
+  const generatedAt = optionalString(checkedAt) || nowIso();
   const kfd1Metadata = resolveKfd1Metadata();
   const normalizedKfd1 = kfd1?.passportSection ? kfd1 : undefined;
   const normalizedKfd3 = kfd3?.passportSection ? kfd3 : undefined;
@@ -1231,6 +1236,8 @@ export function createReleasePassport({
       : [],
     requirePassed: true,
   });
+  const normalizedGitHubArtifactAttestations = (githubArtifactAttestations || [])
+    .map(normalizeGitHubArtifactAttestationPolicy);
   const publishArtifacts = normalizedPublishEvidence?.artifacts || [];
   const normalizedPublishSummary = normalizePublishSummary({
     packageSet: normalizedPackageSet,
@@ -1360,6 +1367,9 @@ export function createReleasePassport({
     ...(normalizedKfdAgentHub ? { kfdAgentHub: normalizedKfdAgentHub } : {}),
     ...(invariantPassports ? { invariantPassports } : {}),
     ...(normalizedControllerReceipts.length > 0 ? { controllerReceipts: normalizedControllerReceipts } : {}),
+    ...(normalizedGitHubArtifactAttestations.length > 0
+      ? { githubArtifactAttestations: normalizedGitHubArtifactAttestations }
+      : {}),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [
@@ -1450,11 +1460,13 @@ export function collectGitHubReleasePassport({
   invariantPassportCommand = "",
   kfdAgentHubEvidenceJson = "",
   controllerReceiptReferences = [],
+  githubArtifactAttestationPolicyJsons = [],
   basePassportJson = "",
   requireBaseKfd = false,
   releaseJsonExtra = "",
   publishJson = "",
   workflow = {},
+  checkedAt = "",
 } = {}) {
   const release = parseJsonInput(releaseJson, {}, { cwd, label: "releaseJson" });
   const releaseExtra = parseJsonInput(releaseJsonExtra, {}, { cwd, label: "releaseJsonExtra" });
@@ -1526,6 +1538,13 @@ export function collectGitHubReleasePassport({
     undefined,
     { cwd, label: "kfdAgentHubEvidenceJson" },
   );
+  const githubArtifactAttestationPolicies = (githubArtifactAttestationPolicyJsons || [])
+    .filter(Boolean)
+    .map((policyJson) => parseJsonInput(policyJson, undefined, {
+      cwd,
+      label: "githubArtifactAttestationPolicyJsons entry",
+    }))
+    .map(normalizeGitHubArtifactAttestationPolicy);
   const kfd3ArtifactWitnesses = [
     ...kfd3ArtifactWitnessMetas.map((meta) => meta.value),
     ...(kfd3ArtifactCommandMeta.value ? [kfd3ArtifactCommandMeta.value] : []),
@@ -1541,6 +1560,7 @@ export function collectGitHubReleasePassport({
   ];
   const resolvedTag = tag || release.tag_name || release.name || "";
   const resolvedOutputDir = path.resolve(cwd, outputDir);
+  const resolvedCheckedAt = optionalString(checkedAt) || nowIso();
   const productMechanism = defaultProductMechanism({ repository, productName });
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: resolvedTag, sourceSha, workflow });
   const bundledPublishEvidencePath = publishEvidenceMeta.value ? "evidence.json" : "";
@@ -1568,7 +1588,7 @@ export function collectGitHubReleasePassport({
         matrixRoot: kfdSupportMatrixMeta.sha256 ? `sha256:${kfdSupportMatrixMeta.sha256}` : "",
         gateResults: kfdProductGateMetas.map((meta) => meta.value),
         expectedSourceSha: sourceSha,
-        checkedAt: nowIso(),
+        checkedAt: resolvedCheckedAt,
       })
     : undefined;
   const passport = mergeAuthoritativePassportBase(createReleasePassport({
@@ -1623,9 +1643,11 @@ export function collectGitHubReleasePassport({
       : undefined,
     kfdAgentHubEvidencePath: kfdAgentHubEvidenceMeta.value ? "kfd-agent-hub-evidence.json" : "",
     controllerReceiptReferences,
+    githubArtifactAttestations: githubArtifactAttestationPolicies,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
+    checkedAt: resolvedCheckedAt,
   }), basePassportMeta.value, { requireKfd: requireBaseKfd });
   if (bundledPublishEvidencePath) {
     passport.evidence.publishEvidence = bundledPublishEvidencePath;
@@ -1639,7 +1661,7 @@ export function collectGitHubReleasePassport({
     productMechanism,
     kfdAgentHubEvidence: kfdAgentHubEvidenceMeta.value,
     kfdSupportEvidence: kfdSupport,
-    checkedAt: nowIso(),
+    checkedAt: resolvedCheckedAt,
   });
   const files = {
     "product-mechanism.json": productMechanism,
@@ -1972,6 +1994,39 @@ export function createReleaseCheckReport({
     issues.push(issue("error", "kfdSupport.section", "KFD support evidence is present without a release-passport projection"));
   }
 
+  for (const [index, value] of (passport?.githubArtifactAttestations || []).entries()) {
+    try {
+      const policy = normalizeGitHubArtifactAttestationPolicy(value);
+      if (policy.caller.sourceSha !== String(passport?.release?.sourceSha || "").toLowerCase()) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].caller.sourceSha`,
+          "attestation policy source SHA must match passport.release.sourceSha",
+        ));
+      }
+      const artifact = (passport?.artifacts || []).find((entry) => entry.name === policy.subject.name);
+      if (!artifact) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].subject.name`,
+          `attestation subject ${policy.subject.name} is absent from the Release Passport artifacts`,
+        ));
+      } else if (artifact.sha256 !== policy.subject.digest.sha256) {
+        issues.push(issue(
+          "error",
+          `githubArtifactAttestations[${index}].subject.digest`,
+          `attestation subject ${policy.subject.name} digest differs from the Release Passport artifact`,
+        ));
+      }
+    } catch (error) {
+      issues.push(issue(
+        "error",
+        `githubArtifactAttestations[${index}]`,
+        error.message,
+      ));
+    }
+  }
+
   const tag = passport?.release?.tag || "";
   if (!tag) {
     issues.push(issue("error", "release.tag", "release.tag is required"));
@@ -2422,6 +2477,7 @@ export async function verifyReleasePassport({
   productMechanismLocation = "",
   kfdAgentHubEvidenceLocation = "",
   kfdSupportEvidenceLocation = "",
+  checkedAt = nowIso(),
 } = {}) {
   const passport = await readJsonFromLocation(passportLocation);
   const basePath = /^https?:\/\//.test(passportLocation) ? passportLocation : path.resolve(passportLocation);
@@ -2462,6 +2518,7 @@ export async function verifyReleasePassport({
     productMechanism,
     kfdAgentHubEvidence,
     kfdSupportEvidence,
+    checkedAt,
   });
 }