@kungfu-tech/buildchain 3.0.2-alpha.3 → 3.0.2-alpha.5

package/dist/site/workflow-registry.json

@@ -111,6 +111,9 @@
         "expected-artifacts-json",
         "fail-fast",
         "gate-profile-aggregate-json",
+        "github-artifact-attestation-platform-id",
+        "github-artifact-attestation-signer-sha",
+        "github-artifact-attestation-subject-path",
         "install-command",
         "kfd-agent-hub",
         "lifecycle-timeout-minutes",
@@ -144,7 +147,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 69,
+      "inputCount": 72,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -355,6 +358,9 @@
         "buildchain-repository",
         "channel",
         "dry-run",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-retention-days",
         "github-governance-receipt-json",
         "github-release",
         "github-release-notes",
@@ -428,7 +434,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 85,
+      "inputCount": 88,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -451,6 +457,10 @@
         "controller-receipt-digest",
         "controller-receipt-json",
         "controller-receipt-status",
+        "github-artifact-attestation-evidence-root",
+        "github-artifact-attestation-id",
+        "github-artifact-attestation-publication-receipt-digest",
+        "github-artifact-attestation-url",
         "promoted-sha",
         "publication-capability-digest",
         "publication-commit-evidence-digest",
@@ -459,7 +469,7 @@
         "publication-commit-url",
         "release-candidate-artifact"
       ],
-      "outputCount": 15,
+      "outputCount": 19,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
@@ -935,6 +945,9 @@
         "expected-artifacts-json",
         "fail-fast",
         "gate-profile-aggregate-json",
+        "github-artifact-attestation-platform-id",
+        "github-artifact-attestation-signer-sha",
+        "github-artifact-attestation-subject-path",
         "install-command",
         "kfd-agent-hub",
         "lifecycle-timeout-minutes",
@@ -968,7 +981,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 72,
+      "inputCount": 75,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1296,6 +1309,40 @@
       "capabilityGroup": "governance-versioning",
       "status": "active"
     },
+    {
+      "id": "github-artifact-attestation",
+      "path": ".github/workflows/github-artifact-attestation.yml",
+      "reusable": true,
+      "inputs": [
+        "buildchain-ref",
+        "environment",
+        "evidence-artifact-name",
+        "evidence-run-id",
+        "platform-manifest-artifact-name",
+        "platform-manifest-relative-path",
+        "policy-json",
+        "release-passport-artifact-name",
+        "release-passport-relative-path",
+        "retention-days",
+        "source-sha",
+        "subject-artifact-name",
+        "subject-relative-path"
+      ],
+      "inputCount": 13,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [
+        "attestation-id",
+        "attestation-url",
+        "bundle-digest",
+        "evidence-artifact-name",
+        "evidence-root"
+      ],
+      "outputCount": 5,
+      "surface": "release-passport",
+      "capabilityGroup": "release-passport-trust",
+      "status": "active"
+    },
     {
       "id": "github-governance-audit",
       "path": ".github/workflows/github-governance-audit.yml",
@@ -1632,6 +1679,9 @@
         "buildchain-stable-contract-lock-path",
         "channel",
         "dry-run",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-retention-days",
         "github-governance-receipt-json",
         "github-release",
         "github-release-notes",
@@ -1694,7 +1744,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 77,
+      "inputCount": 80,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1718,6 +1768,10 @@
         "controller-receipt-digest",
         "controller-receipt-json",
         "controller-receipt-status",
+        "github-artifact-attestation-evidence-root",
+        "github-artifact-attestation-id",
+        "github-artifact-attestation-publication-receipt-digest",
+        "github-artifact-attestation-url",
         "promoted-sha",
         "promotion-contract-lock-digest",
         "promotion-contract-lock-path",
@@ -1737,7 +1791,7 @@
         "publication-commit-url",
         "release-candidate-artifact"
       ],
-      "outputCount": 27,
+      "outputCount": 31,
       "surface": "release-governance",
       "capabilityGroup": "reusable-build",
       "status": "active"
@@ -1932,6 +1986,28 @@
   ],
   "actionSource": "actions/*/action.yml reverse input enumeration",
   "actions": [
+    {
+      "id": "github-artifact-attestation",
+      "path": "actions/github-artifact-attestation/action.yml",
+      "inputs": [
+        "attestation-id",
+        "attestation-url",
+        "bundle-path",
+        "expected-buildchain-ref",
+        "expected-caller-repository",
+        "expected-source-sha",
+        "mode",
+        "output-dir",
+        "platform-manifest-path",
+        "policy-json",
+        "preparation-json",
+        "release-passport-path",
+        "subject-path"
+      ],
+      "inputCount": 13,
+      "capabilityGroup": "release-passport-trust",
+      "status": "active"
+    },
     {
       "id": "macos-credential-island",
       "path": "actions/macos-credential-island/action.yml",
@@ -2006,6 +2082,7 @@
         "release-passport",
         "release-passport-build-summary-path",
         "release-passport-buildchain-self-kfd",
+        "release-passport-github-artifact-attestation-policy-jsons",
         "release-passport-impact-json",
         "release-passport-invariant-passport-command",
         "release-passport-invariant-passport-jsons",
@@ -2032,7 +2109,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 66,
+      "inputCount": 67,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/MAP.md

@@ -27,7 +27,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability group | Primary facts | Primary manuals |
 | --- | --- | --- |
 | Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
-| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
+| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
 | Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
@@ -42,6 +42,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
 | Product invariant Passport release gate | `buildchain.release.json#invariantPassports`, `dist/site/buildchain-contract.json` | [`release-passport.md`](release-passport.md) |
+| GitHub keyless Linux artifact attestation | `buildchain.release.json#githubArtifactAttestations`, `dist/site/workflow-registry.json`, `dist/site/artifact-schemas.json` | [`github-artifact-attestation.md`](github-artifact-attestation.md) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
 | KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Declarative KFD Agent Hub adapter conformance and Passport evidence | `.buildchain/kfd/agent-hub.json`, `.buildchain/artifacts/kfd-agent-hub/evidence.json`, `buildchain.release.json#kfdAgentHub` | [`kfd-agent-hub.md`](kfd-agent-hub.md) |
@@ -85,6 +86,7 @@ replace them.
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I keylessly attest Linux release artifacts with GitHub and bind them to a Release Passport? | [`github-artifact-attestation.md`](github-artifact-attestation.md) | verify/use | preview |
 | How do I seal exact artifact, identity, lifecycle, and KFD assessment roots for KFX admission? | [`artifact-verification-envelope.md`](artifact-verification-envelope.md) | verify/use | preview |
 | How is product publication authority sealed to an exact workflow, runner, control plane, nonce, and artifact? | [`publication-authority.md`](publication-authority.md) | verify | preview |
 | How are GitHub ownership, independent review, effective protection, and plan capability audited fail-closed? | [`github-governance-authority.md`](github-governance-authority.md) | verify | preview |

package/docs/binary-distribution.md

@@ -47,6 +47,13 @@ Each archive is accompanied by:
 - `buildchain-release-bundle.tar.gz`;
 - `buildchain-release-bundle.json`.
 
+Linux archives may also be accompanied by a GitHub/Sigstore bundle and
+`buildchain.github-artifact-attestation-evidence/v1`. These prove the exact
+GitHub signer workflow and source digest while preserving the original compiler
+runner in the platform manifest. The GitHub-hosted signer does not rebuild or
+execute consumer source. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 ## KFD-3 Distribution Declaration
 
 Buildchain self-describes this release lane in `dist/site/kfd-claims.json` as

package/docs/cli.md

@@ -74,6 +74,7 @@ import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
 import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain/badges";
 import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
+import { verifyGitHubArtifactAttestationEvidence } from "@kungfu-tech/buildchain/github-artifact-attestation";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
@@ -92,6 +93,14 @@ floating-ref contract world for a runtime such as `@v3`.
 
 ## Commands
 
+`buildchain create github-artifact-attestation-policy` seals the expected
+artifact, caller source, original Linux build, immutable Buildchain signer, and
+GitHub permission set before the Release Passport is collected.
+`buildchain verify github-artifact-attestation` invokes `gh attestation verify`
+with the exact signer/source policy and then verifies the retained bundle,
+predicate, platform manifest, Passport, and Buildchain evidence locally. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 `buildchain layout` is the stable machine question for repository layout. Tools
 such as Shifu should call it instead of copying `.buildchain/` path constants:
 

package/docs/dev-alpha-candidate-patrol.md

@@ -21,14 +21,26 @@ ai_provenance:
 
 Buildchain provides a reusable observation and PR controller for repositories
 that promote a development branch into a protected Alpha branch. It does not
-publish Alpha. The controller reads the exact heads of both branches and accepts
-the development head only when:
+publish Alpha. The controller reads the exact heads of both branches, walks the
+bounded development history from newest to oldest (stopping early at the Alpha
+head), and selects the newest commit that satisfies all of these conditions:
 
 - the source is strictly ahead of the recorded target head;
-- the latest completed Dev Patrol for that exact source SHA succeeded;
-- the latest completed Alpha preflight for the same SHA succeeded; and
+- the latest completed Dev Patrol for that exact commit SHA succeeded;
+- the latest completed Alpha preflight for the same commit SHA succeeded; and
 - both runs are within the caller's evidence age limit.
 
+The selected commit can be behind the observed development head when newer
+commits have not completed both workflows yet. The decision binds the observed
+head, selected SHA, and count of skipped newer commits. This makes a slow native
+verification lane live under continuous development without silently treating
+an unqualified head as releasable.
+
+History discovery is bounded to the newest 1000 development commits. The
+controller then compares the selected SHA to the exact Alpha head before it can
+be eligible, so a bounded scan cannot turn a commit outside the promotion
+ancestry into a candidate.
+
 The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the
 source and target branches and SHAs, comparison distance, workflow paths, run
 identities and attempts, completion times, URLs, policy, and a canonical decision

package/docs/github-artifact-attestation.md

@@ -0,0 +1,219 @@
+---
+status: draft
+period: 2026-07
+theme: buildchain-linux-artifact-provenance
+doc_type: protocol
+source_level: code-and-official-docs
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-24
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-24
+  visible_context: Buildchain source, tests, GitHub Actions documentation, and actions/attest documentation
+  invisible_context: Model internals and provider-side implementation details are not visible
+---
+
+# GitHub-native Linux Artifact Attestation
+
+Buildchain can bind a Linux release artifact to its original compiler run, exact
+source revision, platform manifest, Release Passport, and an immutable
+Buildchain attester workflow. GitHub's OIDC identity and artifact attestation
+service provide the keyless signature; Buildchain provides the release contract
+and fail-closed local verification.
+
+This capability proves provenance and integrity. It does not prove that source
+code is safe, that a compiler was uncompromised, or that a self-hosted build
+runner had no privileged observer.
+
+## Trust Boundary
+
+The original Linux runner remains the compiler identity. The reusable attester
+runs on `ubuntu-24.04` only after the artifact, platform manifest, and Release
+Passport have been sealed and uploaded. It downloads those files as data and
+never checks out or executes consumer source.
+
+The attester checks out only
+`actions/github-artifact-attestation` from an exact Buildchain commit. It
+rejects a floating Buildchain ref, a different caller repository, a different
+source SHA, a different workflow run, a non-Linux platform manifest, or a
+subject digest absent from the Release Passport.
+
+The protected Environment defaults to `buildchain-artifact-attestation`.
+Consumer repositories should require review or restrict deployment branches on
+that Environment when their release policy requires an independent gate.
+
+## Non-circular Passport Binding
+
+The Release Passport first records
+`githubArtifactAttestations[]`, an immutable expected-attestation policy:
+
+- artifact name, relative path, byte size, and SHA-256;
+- caller repository, source commit, and source tree;
+- original Linux platform and platform-manifest digest; the initial v3 contract
+  requires the runner receipt root to equal that exact manifest digest;
+- Buildchain signer workflow path and exact signer-bootstrap commit;
+- exact Buildchain runtime commit used to build and release the artifact;
+- exact GitHub permission set.
+
+The GitHub attestation predicate then records the completed Release Passport
+file digest. The returned attestation id, URL, Sigstore bundle digest, and
+predicate root are written to a separate
+`buildchain.github-artifact-attestation-evidence/v1` document. Keeping dynamic
+provider evidence outside the Passport avoids a self-referential hash while
+still binding both directions.
+
+## GitHub Permissions and Runtime Pins
+
+Both caller and reusable workflow grant only:
+
+```yaml
+permissions:
+  actions: read
+  artifact-metadata: write
+  attestations: write
+  contents: read
+  id-token: write
+```
+
+The reusable workflow pins `actions/checkout`, `actions/download-artifact`,
+`actions/upload-artifact`, and `actions/attest` by full commit SHA. The workflow
+itself must also be called at its exact signer-bootstrap commit. The signer
+commit and the later Buildchain runtime commit are separately bound so the
+first v3 integration never relies on a mutable or self-referential workflow ref.
+
+## Prepare the Release Passport
+
+Create one input document for each Linux artifact and seal it as a policy:
+
+```bash
+buildchain create github-artifact-attestation-policy \
+  --input-json .buildchain/github-artifact-attestation/policy-input.json \
+  --output .buildchain/github-artifact-attestation/policy.json
+```
+
+The input object contains `subject`, `caller`, `signer`, and `build` objects.
+The CLI computes no trusted values implicitly: the caller supplies the already
+measured subject size/digest, source commit/tree, platform-manifest digest,
+runner receipt root, and exact Buildchain workflow commit.
+
+Pass the policy into Release Passport collection:
+
+```bash
+buildchain collect github-release \
+  --github-artifact-attestation-policy-json \
+    .buildchain/github-artifact-attestation/policy.json \
+  --output-dir .buildchain/release-passport \
+  # ...the existing release inputs
+```
+
+The build, Passport, and attestation jobs must stay in the same workflow run.
+The release-candidate build declares both the subject and the already-merged
+signer bootstrap commit. The Buildchain runtime remains the exact runtime ref
+used by the build workflow and may be a later commit:
+
+```yaml
+with:
+  github-artifact-attestation-subject-path: dist/kungfu-linux-x64.tar.gz
+  github-artifact-attestation-signer-sha: <exact-signer-bootstrap-sha>
+  github-artifact-attestation-platform-id: linux-x64
+```
+
+For release promotion, prefer the integrated v3 route. The policy must already
+be present in the downloaded release-candidate payload:
+
+```yaml
+permissions:
+  actions: write
+  artifact-metadata: write
+  attestations: write
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@<exact-buildchain-v3-runtime-sha>
+    with:
+      buildchain-ref: <exact-buildchain-v3-runtime-sha>
+      github-release: true
+      release-passport: true
+      github-artifact-attestation-policy-json: .buildchain/release-candidate/payload/<artifact>/policy.json
+      github-artifact-attestation-environment: buildchain-artifact-attestation
+```
+
+Promotion binds the policy into the Passport, stages only digest-matching data,
+calls the exact v3 signer, verifies the provider identity a second time, and
+publishes immutable bundle, predicate, verification, evidence, and receipt
+assets beside the release artifact. A same-name Release asset with different
+bytes is rejected instead of overwritten.
+
+Low-level callers may call the reusable attester directly after their Passport
+job. Both the reusable workflow ref and `buildchain-ref` use the same exact
+40-hex signer-bootstrap commit and fail closed if the provider identity differs:
+
+```yaml
+jobs:
+  attest-linux:
+    needs: [build-linux, release-passport]
+    permissions:
+      actions: read
+      artifact-metadata: write
+      attestations: write
+      contents: read
+      id-token: write
+    uses: kungfu-systems/buildchain/.github/workflows/github-artifact-attestation.yml@<exact-signer-bootstrap-sha>
+    with:
+      buildchain-ref: <exact-signer-bootstrap-sha>
+      evidence-run-id: ${{ github.run_id }}
+      source-sha: ${{ github.sha }}
+      subject-artifact-name: linux-release
+      subject-relative-path: libnode-linux-x64.tar.gz
+      platform-manifest-artifact-name: linux-platform-manifest
+      platform-manifest-relative-path: manifest.json
+      release-passport-artifact-name: release-passport
+      release-passport-relative-path: buildchain.release.json
+      policy-json: ${{ needs.release-passport.outputs.github-attestation-policy-json }}
+      evidence-artifact-name: linux-attestation-evidence
+```
+
+## Verify Online and Offline
+
+The Buildchain verifier reconstructs exact `gh attestation verify` arguments
+from the policy, including repository, signer workflow, signer digest, source
+digest, predicate type, and self-hosted-runner denial. It then verifies the
+local artifact, platform manifest, Release Passport, retained Sigstore bundle,
+custom predicate, and Buildchain evidence root:
+
+The reusable workflow runs that same exact signer/source verification
+immediately after `actions/attest` and before it finalizes or uploads evidence.
+Passing a different `buildchain-ref` than the commit used to invoke the reusable
+workflow therefore fails in the signer job, not only during later consumption.
+The policy additionally retains the distinct Buildchain runtime SHA that
+created the build and release evidence.
+
+```bash
+buildchain verify github-artifact-attestation \
+  --artifact libnode-linux-x64.tar.gz \
+  --platform-manifest manifest.json \
+  --release-passport buildchain.release.json \
+  --bundle attestation.sigstore.json \
+  --evidence github-artifact-attestation.evidence.json
+```
+
+Verification fails if a single artifact byte changes, the source commit or
+repository differs, the signer workflow or Buildchain commit differs, the
+Passport was replaced, the platform manifest drifts, the bundle omits the
+expected statement, or GitHub reports a self-hosted signer.
+
+## Qualification Policy
+
+New protocol work qualifies on the Buildchain v3 alpha line first. The v2
+development branch is not a supported landing target. Production
+adoption waits for the exact v3 implementation commit to pass the repository
+suite and a real GitHub OIDC/Sigstore qualification run, including the negative
+cases above. A successful local fixture is necessary but not sufficient.

package/docs/release-passport.md

@@ -8,6 +8,14 @@ promotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and
 machine-readable evidence. A project can keep its existing build system and use
 Buildchain to make the release record auditable.
 
+Linux release artifacts can additionally carry a GitHub keyless attestation
+policy in `githubArtifactAttestations[]`. The policy binds the exact subject,
+consumer source, original Linux build evidence, immutable Buildchain signer
+workflow, and minimum permissions before the provider attestation exists. The
+completed provider bundle and attestation identifier remain separate evidence,
+avoiding a Passport hash cycle. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 Release-candidate and final passports may also include compact
 `controllerReceipts[]` references. These bind a real reusable-workflow receipt
 to its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they
@@ -91,6 +99,10 @@ Additive passport sections:
   semantic Passport root, exact clean source revision, complete platform
   coverage, verdict, and residual risk. Buildchain owns release admission, not
   the meaning of the product invariants.
+- `githubArtifactAttestations`: expected GitHub keyless attestation identities
+  for Linux release artifacts, including subject, caller source, original build
+  evidence, exact Buildchain signer workflow digest, and least-privilege
+  permissions. Dynamic provider evidence is stored beside the Passport.
 
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:
@@ -144,6 +156,7 @@ buildchain collect github-release \
   --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --invariant-passport-json product/release/qualification/invariant-passport.json \
+  --github-artifact-attestation-policy-json .buildchain/github-artifact-attestation/policy.json \
   --output-dir .buildchain/release-passport
 ```
 

package/docs/reusable-build-surface.md

@@ -5,6 +5,12 @@ Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
 
+For Linux release artifacts, the build workflow can hand the sealed artifact,
+platform manifest, and Release Passport to the separate GitHub-hosted keyless
+attester. The compiler runner remains the recorded build identity; the attester
+only signs and verifies immutable data. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 ## Automatic Channel Router
 
 The preferred consumer surface is one reusable workflow call. After v2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.2-alpha.3",
+  "version": "3.0.2-alpha.5",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -17,6 +17,7 @@
     "./core": "./packages/core/index.js",
     "./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",
     "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./candidate-timeline": "./packages/core/candidate-timeline.js",

package/packages/core/buildchain-contract.js

@@ -121,6 +121,8 @@ export function createBuildchainContractWorld({
         "runner-preset",
         "platforms-json",
         "release-candidate",
+        "github-artifact-attestation-subject-path",
+        "github-artifact-attestation-platform-id",
         "artifact-transfer-mode",
         "checkout-cache-mode",
         "checkout-cache-fallback",
@@ -196,6 +198,9 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-retention-days",
         "buildchain-contract-lock-path",
         "buildchain-contract-drift-issue-mode",
         "github-release",
@@ -369,6 +374,7 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "release-passport-github-artifact-attestation-policy-jsons",
         "github-release",
         "github-release-title",
         "github-release-notes",

package/packages/core/buildchain-kfd-claims.js

@@ -16,6 +16,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
   { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
+  { id: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.md", plane: "verify" },
   { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
   { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
   { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
@@ -71,6 +72,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
 const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/kfd-gate.js",
   "packages/core/release-passport.js",
+  "packages/core/github-artifact-attestation.js",
   "packages/core/buildchain-contract.js",
   "packages/core/controller-evidence.js",
   "packages/core/publication-authority.js",
@@ -89,6 +91,9 @@ const WORKFLOW_AND_ACTION_FILES = Object.freeze([
   ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/github-artifact-attestation.yml",
+  "actions/github-artifact-attestation/action.yml",
+  "actions/github-artifact-attestation/index.js",
   ".github/workflows/release-propagation.yml",
   "actions/macos-credential-island/action.yml",
   "actions/macos-credential-island/index.js",

package/packages/core/buildchain-publication-authority.js

@@ -31,6 +31,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
   [".github/workflows/github-governance-audit.yml", "governance-write"],
+  [".github/workflows/github-artifact-attestation.yml", "evidence-publication", true, ["github-artifact-attestation"], "oidc", "consumer-defined", "caller-bound", "caller-bound"],
   [".github/workflows/npm-publish.yml", "dry-run-only"],
   [".github/workflows/paper-release-sealed.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/paper-release.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],