@kungfu-tech/buildchain 3.0.2-alpha.7 → 3.0.2-alpha.8

package/docs/reusable-build-surface.md

@@ -1,3 +1,21 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-reusable-build
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-27
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-27
+  invisible_context: not asserted
+---
+
 # Reusable Build Surface
 
 Buildchain v2 provides a reusable build workflow for repositories that need
@@ -35,7 +53,7 @@ jobs:
 
 `buildchain-channel` defaults to `auto`. Selection uses this precedence:
 
-1. an explicit `buildchain-ref` train, SHA, or official channel;
+1. an explicit `buildchain-ref` protected authority, train, SHA, or official channel;
 2. an explicit `buildchain-channel: alpha|stable`;
 3. `publish-channel: alpha|release|major`;
 4. GitHub release prerelease metadata;
@@ -482,8 +500,8 @@ The reusable workflow exposes the resolved contract:
 | `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |
 | `buildchain-runtime-ref`          | Runtime ref selected after applying the empty-default or override policy        |
 | `buildchain-runtime-sha`          | Immutable Buildchain runtime commit used by all runtime checkouts               |
-| `buildchain-runtime-class`        | `stable`, `alpha`, `train`, `exact-sha`, or `development`                       |
-| `buildchain-runtime-override`     | `true` when a train or exact-SHA `buildchain-ref` override was accepted          |
+| `buildchain-runtime-class`        | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`          |
+| `buildchain-runtime-override`     | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted |
 | `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |
 | `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
 | `buildchain-contract-lock-drift`  | `true` when the floating runtime SHA or contract digest changed                 |
@@ -523,65 +541,62 @@ release jobs can detect drifting diagnostics JSON contracts and missing or
 drifting diagnostics sidecar manifests without downloading the per-platform
 diagnostics artifacts first.
 
-## macOS Credential Island
-
-Alpha consumers can ask the build controller to seal one exact macOS app and
-hand it to a separate protected signing job. The built-in mode is suitable
-when the protected environment belongs to the repository that defines the
-reusable workflow:
+## Artifact Signing Authority
 
-```yaml
-with:
-  credential-island-macos-app-path: product/dist/desktop/mac-arm64/Kungfu Episodes.app
-  credential-island-environment: alpha-macos-signing
-  credential-island-macos-platform-id: macos-arm64
-```
+Artifact signing is a Buildchain capability, not a macOS application workflow.
+Consumers declare desired signature state next to their artifact facts; they do
+not configure certificates, Team IDs, notary credentials, protected
+environments, authority roles, or signing jobs:
 
-For a cross-repository reusable workflow, keep the credentials in the consumer
-repository and select caller-owned mode:
-
-```yaml
-with:
-  credential-island-macos-app-path: product/dist/desktop/mac-arm64/Kungfu Episodes.app
-  credential-island-caller-owned: true
-  credential-island-macos-platform-id: macos-arm64
+```toml
+[[signing.artifacts]]
+id = "native-engine"
+path = "dist/kungfu-engine"
+profile = "auto"
+kind = "mach-o"
+platforms = ["macos-arm64", "macos-x64"]
 ```
 
-The caller then runs its own no-checkout macOS job after the reusable build,
-binds the consumer-owned protected environment on that job, and downloads the
-source-bound input plus immutable action runtime from the same workflow run.
-This is required for cross-repository callers because environment credentials
-must never be widened into repository secrets merely to cross a reusable
-workflow boundary.
-
-The ordinary matrix uploads
-`credential-island-input-<platform>-<source-sha>`, containing a `ditto`
-archive and a manifest bound to the caller repository, source commit, source
-tree, bundle identity, version, size, and digest. The pinned reusable workflow
-either starts its built-in GitHub-hosted macOS job or leaves that job to the
-caller. In both modes the credential-bearing job has no source checkout or
-package-manager step: it downloads the immutable Buildchain action runtime plus
-the sealed app and never invokes consumer code.
-
-The protected environment supplies these non-secret variables:
-
-- `BUILDCHAIN_MACOS_EXPECTED_BUNDLE_ID`
-- `BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`
-- `BUILDCHAIN_MACOS_CERTIFICATE_SHA1`
-
-and these secrets:
-
-- `BUILDCHAIN_MACOS_CERTIFICATE_P12_BASE64`
-- `BUILDCHAIN_MACOS_CERTIFICATE_PASSWORD`
-- `BUILDCHAIN_MACOS_NOTARY_API_KEY_P8_BASE64`
-- `BUILDCHAIN_MACOS_NOTARY_API_KEY_ID`
-- `BUILDCHAIN_MACOS_NOTARY_API_ISSUER`
-
-The signed DMG, signed app ZIP, credential evidence, and their source-bound
-platform manifest form one additional release-candidate platform. Reviewers can
-therefore verify the exact caller source and immutable Buildchain runtime that
-entered the credential island before admitting or publishing the signed
-artifacts.
+Every native and container build lane reads this declaration after the build
+lifecycle and before verification. Buildchain binds the exact artifact bytes or directory tree to
+the caller repository, source commit, source tree, immutable runtime, platform,
+and requested signature semantics, then publishes a deterministic
+`<artifact>-signing-request-<platform>-<source-sha>` request. No consumer
+workflow step is required.
+
+`profile = "auto"` resolves signable Apple artifacts such as Mach-O files,
+`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, and `.dmg` to the
+native `apple-developer-id` provider. Windows `pe` and `binary` artifacts
+resolve to timestamped native `windows-authenticode`; Windows PE never falls
+back to a detached signature. Linux and other non-native binary files,
+archives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a
+detached cryptographic signature and never misrepresents it as an operating
+system code signature. Explicit incompatible provider/kind/platform
+combinations fail closed.
+
+The request schema rejects credential and authority-infrastructure fields. The
+Buildchain-owned signing authority is responsible for credential selection,
+native signing, notarization where applicable, immutable result delivery, and a
+receipt bound to the request digest, runtime SHA, output digest, and signature
+evidence. Consumer repositories neither receive nor duplicate credential-island
+material. The reusable workflow dispatches the sealed request to the
+Buildchain repository, waits for its protected authority workflow, verifies the
+immutable result, replaces only the declared artifact with the returned final
+bytes, and then runs the consumer's normal verification. Platform manifests,
+KFD evidence, checksums, and Release Passport inputs therefore observe the
+final signed artifact rather than the pre-signing build output.
+
+The durable v3 authority runtime is
+`authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable
+release work use the same protected `buildchain-artifact-signing` environment
+and provider identities. The authority ref is protected independently from
+release channels and can advance only through reviewed, checked changes; the
+temporary `train/v3/v3.0/artifact-signing-authority` ref is retained only as a
+bounded migration rollback.
+
+The older `credential-island-macos-*` reusable-workflow inputs remain a
+compatibility surface while existing callers migrate. They are not the target
+consumer contract and must not be used to design new integrations.
 
 ## Artifact Transfer Relay
 

package/docs/runtime-train-validation.md

@@ -64,6 +64,27 @@ item that still needs to be merged; it is only a temporary fast-use,
 diagnostic, and rollback channel for initiating repositories. Retained trains
 are cleaned up by a separate periodic Buildchain cleanup task.
 
+## Formal artifact-signing authority ref
+
+Artifact signing uses a durable, channel-neutral authority ref after its
+runtime has passed downstream validation:
+
+```text
+authority/v3/v3.0/artifact-signing
+```
+
+Unlike a train, this ref is a protected execution boundary. Alpha and stable
+release intent use the same authority ref and the same
+`buildchain-artifact-signing` environment; channel promotion never selects a
+different certificate environment. Updates to the authority ref require a
+reviewed pull request, the normal `check` and `verify` status contexts, and a
+fast-forward-safe protected branch policy. Deletion and non-fast-forward
+updates are forbidden.
+
+The temporary `train/v3/v3.0/artifact-signing-authority` ref remains a bounded
+rollback and diagnostic pointer during migration. It is not the production
+identity and must not regain credential ownership.
+
 ## Consumer workflow requirement
 
 Consumers keep their reusable workflow pinned to the stable shell:

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-28 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default. | |
 | 2026-07-26 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-evidence | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle. | #1862 |
 | 2026-07-23 | extend-minor | `v2.14` | credential-island-macos-input, protected-signer-job, macos-signing-evidence, action-subpaths | additive | The reusable build surface can seal an exact source-bound macOS app and hand it to a protected caller environment, where an immutable Buildchain action signs, notarizes, staples, Gatekeeper-assesses, and returns an auditable additional release-candidate platform without exposing credentials to consumer lifecycle jobs. | |
 | 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.2-alpha.7",
+  "version": "3.0.2-alpha.8",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -18,6 +18,9 @@
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
     "./github-artifact-attestation": "./packages/core/github-artifact-attestation.js",
+    "./artifact-signing": "./packages/core/artifact-signing.js",
+    "./artifact-signing-result": "./packages/core/artifact-signing-result.js",
+    "./detached-artifact-signature": "./packages/core/detached-artifact-signature.js",
     "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./candidate-timeline": "./packages/core/candidate-timeline.js",
@@ -82,6 +85,7 @@
     "AGENTS.md",
     "bin/",
     "CONTRIBUTING.md",
+    "contracts/",
     "LICENSE-POLICY.md",
     "scripts/*.mjs",
     "packages/core/",

package/packages/core/artifact-signing-result.js

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  ARTIFACT_SIGNING_AUTHORITY_CONTRACT,
+  artifactSigningDigest,
+  validateArtifactSigningReceipt,
+  validateArtifactSigningRequest,
+} from "./artifact-signing.js";
+
+export const ARTIFACT_SIGNING_RESULT_CONTRACT =
+  "kungfu-buildchain-artifact-signing-result/v1";
+
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function digest(value, label) {
+  const normalized = required(value, label).toLowerCase();
+  if (!SHA256_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be a sha256 digest`);
+  }
+  return normalized;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function documentDigest(value) {
+  const { digest: _digest, ...basis } = value;
+  return artifactSigningDigest(basis);
+}
+
+function normalizeEvidence(evidence = []) {
+  if (!Array.isArray(evidence) || evidence.length === 0) {
+    throw new Error("artifact signing result requires verification evidence");
+  }
+  return evidence.map((entry, index) => ({
+    kind: required(entry?.kind, `evidence[${index}].kind`),
+    path: required(entry?.path, `evidence[${index}].path`),
+    digest: digest(entry?.digest, `evidence[${index}].digest`),
+  }));
+}
+
+export function artifactSigningEvidenceDigest(evidence = []) {
+  const normalized = normalizeEvidence(evidence);
+  return artifactSigningDigest(
+    normalized.map(({ kind, digest: entryDigest }) => ({
+      kind,
+      digest: entryDigest,
+    })),
+  );
+}
+
+export function createArtifactSigningResult({
+  request,
+  receipt,
+  receiptPath = "receipt.json",
+  payload = {},
+  evidence = [],
+  verification = {},
+} = {}) {
+  const requestCheck = validateArtifactSigningRequest(request);
+  if (!requestCheck.ok) {
+    throw new Error(
+      `invalid artifact signing request: ${requestCheck.issues.join(", ")}`,
+    );
+  }
+  const receiptCheck = validateArtifactSigningReceipt(receipt, { request });
+  if (!receiptCheck.ok || receipt?.status !== "passed") {
+    throw new Error(
+      `invalid passed artifact signing receipt: ${receiptCheck.issues.join(", ")}`,
+    );
+  }
+  const normalizedEvidence = normalizeEvidence(evidence);
+  const evidenceDigest = artifactSigningEvidenceDigest(normalizedEvidence);
+  const payloadDigest = digest(payload.digest, "payload digest");
+  const payloadBytes = Number(payload.bytes);
+  if (!Number.isSafeInteger(payloadBytes) || payloadBytes < 0) {
+    throw new Error("payload bytes must be a non-negative safe integer");
+  }
+  if (receipt.result?.artifactDigest !== payloadDigest) {
+    throw new Error("receipt artifact digest does not bind the result payload");
+  }
+  if (receipt.result?.evidenceDigest !== evidenceDigest) {
+    throw new Error("receipt evidence digest does not bind the result evidence");
+  }
+  const provider = required(verification.provider, "verification provider");
+  if (provider !== request.signature.provider) {
+    throw new Error("verification provider does not match the requested provider");
+  }
+  if (verification.status !== "passed") {
+    throw new Error("artifact signing result verification must pass");
+  }
+  if (!Array.isArray(verification.checks) || verification.checks.length === 0) {
+    throw new Error("artifact signing result requires provider verification checks");
+  }
+  const result = {
+    schemaVersion: 1,
+    contract: ARTIFACT_SIGNING_RESULT_CONTRACT,
+    requestDigest: request.digest,
+    authority: {
+      contract: ARTIFACT_SIGNING_AUTHORITY_CONTRACT,
+      id: receipt.authority.id,
+      runtimeSha: receipt.authority.runtimeSha,
+    },
+    source: { ...request.source },
+    signature: { ...request.signature },
+    artifact: {
+      id: request.artifact.id,
+      inputDigest: request.artifact.digest,
+      path: required(payload.path, "payload path"),
+      bytes: payloadBytes,
+      digest: payloadDigest,
+    },
+    evidence: normalizedEvidence,
+    evidenceDigest,
+    verification: {
+      status: "passed",
+      provider,
+      checks: verification.checks.map((check, index) =>
+        required(check, `verification.checks[${index}]`),
+      ),
+    },
+    receipt: {
+      path: required(receiptPath, "receipt path"),
+      digest: digest(receipt.digest, "receipt digest"),
+    },
+  };
+  result.digest = documentDigest(result);
+  return result;
+}
+
+export function validateArtifactSigningResult(result, { request, receipt } = {}) {
+  const issues = [];
+  try {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+      throw new Error("artifact signing result must be an object");
+    }
+    if (result.contract !== ARTIFACT_SIGNING_RESULT_CONTRACT) {
+      issues.push("artifact signing result contract mismatch");
+    }
+    const rebuilt = createArtifactSigningResult({
+      request,
+      receipt,
+      receiptPath: result.receipt?.path,
+      payload: result.artifact,
+      evidence: result.evidence,
+      verification: result.verification,
+    });
+    if (result.digest !== rebuilt.digest) {
+      issues.push("artifact signing result digest mismatch");
+    }
+    if (stableJson(result) !== stableJson(rebuilt)) {
+      issues.push("artifact signing result contains unsupported or stale fields");
+    }
+  } catch (error) {
+    issues.push(String(error?.message || error));
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+function resolveFile(root, relative, label) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, required(relative, label));
+  const rel = path.relative(resolvedRoot, resolved);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`${label} must resolve below the result root`);
+  }
+  return resolved;
+}
+
+function sha256File(filePath) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(filePath))
+    .digest("hex")}`;
+}
+
+export function verifyArtifactSigningResultFiles({
+  root,
+  request,
+  receipt,
+  result,
+} = {}) {
+  const issues = [];
+  const resultCheck = validateArtifactSigningResult(result, { request, receipt });
+  issues.push(...resultCheck.issues);
+  try {
+    const payloadPath = resolveFile(root, result.artifact.path, "payload path");
+    const stat = fs.statSync(payloadPath);
+    if (!stat.isFile()) issues.push("result payload is not a regular file");
+    if (stat.size !== result.artifact.bytes) issues.push("result payload byte count mismatch");
+    if (sha256File(payloadPath) !== result.artifact.digest) {
+      issues.push("result payload digest mismatch");
+    }
+    const receiptPath = resolveFile(root, result.receipt.path, "receipt path");
+    const receiptFromFile = JSON.parse(fs.readFileSync(receiptPath, "utf8"));
+    if (
+      receiptFromFile.digest !== result.receipt.digest ||
+      stableJson(receiptFromFile) !== stableJson(receipt)
+    ) {
+      issues.push("result receipt file does not match the bound receipt");
+    }
+    for (const entry of result.evidence || []) {
+      const evidencePath = resolveFile(root, entry.path, "evidence path");
+      if (sha256File(evidencePath) !== entry.digest) {
+        issues.push(`result evidence digest mismatch: ${entry.kind}`);
+      }
+    }
+  } catch (error) {
+    issues.push(String(error?.message || error));
+  }
+  return { ok: issues.length === 0, issues };
+}