release/sbom: Publish dependency and license evidence

[idy]

Background

This issue supersedes h2vivi/firmwares#548 after public dependencies, Bazel vendor repositories, firmware packages and the Release workflow moved to GizOS.

GizOS currently pins public upstream archives by immutable URL, revision/strip prefix and SHA-256 in MODULE.bazel, and //tools/bazel:firmware_release_bundle validates firmware identity and asset checksums. The release does not yet emit a machine-readable SBOM or human-readable third-party notices from those same dependency and artifact graphs. There is no existing GizOS Issue or implementation for this capability.

Goal

Generate deterministic SPDX 2.3 JSON and THIRD_PARTY_NOTICES.txt for the public artifacts produced by the GizOS Release workflow, reconcile them with the Bazel dependency/release graph, and fail closed when a redistributed dependency lacks provenance or license evidence.

Non-goals

• Do not aggregate proprietary Firmwares products, private boards, private product assets or private release policy.
• Do not restore the retired Firmwares Desktop Lab SBOM/package layout.
• Do not publish credentials, machine-local SDK paths, build-host paths, caches or non-distributable private source.
• Do not make automated legal conclusions, approve licenses, scan vulnerabilities or replace Dependabot/security tooling.
• Do not treat host operating-system services or toolchains that are not redistributed as bundled release components.
• Do not edit upstream copyright or license text.

Code Changes Tree

MODULE.bazel                                      # attach SPDX identity, version, license expression and license-file inputs to redistributed pinned vendor repositories
tools/bazel/vendor/repositories.bzl              # validate canonical provenance/license fields and expose deterministic metadata from each vendor repository
tools/bazel/sbom/BUILD.bazel                     # define SBOM, notice, reconciliation and negative-fixture test targets
tools/bazel/sbom/generate_sbom.py                # generate deterministic SPDX 2.3 JSON from canonical vendor metadata and release graph inputs
tools/bazel/sbom/generate_notices.py             # assemble stable human-readable notices from the exact upstream license texts
tools/bazel/sbom/reconcile_release.py             # fail on missing, stale or undeclared redistributed components and reject private paths
tools/bazel/sbom/tests/test_generate_sbom.py      # cover schema, ordering, relationships, integrity and reproducibility
tools/bazel/sbom/tests/test_generate_notices.py   # cover license-text attribution, stable ordering and missing-text failure
tools/bazel/sbom/tests/test_reconcile_release.py  # cover graph/package mismatch, system-library exclusions and private-path rejection
tools/bazel/BUILD.bazel                          # wire public release SBOM/notices into the existing firmware release bundle target
tools/bazel/release_bundle.bzl                   # declare SBOM/notice inputs as required release-bundle artifacts
tools/bazel/release_bundle.py                    # validate, copy and checksum SBOM/notice sidecars with the existing release assets
tools/bazel/tests/test_release_bundle.py          # prove missing or mismatched compliance artifacts fail bundle assembly
.github/workflows/release.yml                    # build, independently validate and publish the generated compliance evidence
guides/zh/developing/bazel.md                    # document canonical dependency metadata, generation commands and fail-closed release contract
guides/zh/developing/repo_layout.md              # add the SBOM tool ownership and generated-output boundary to the repository layout

Generated SBOMs and notices are Bazel/release outputs, not committed source files. Canonical metadata, generators, tests and the rules that bind upstream license inputs are committed.

Design

Canonical dependency metadata

Extend the existing vendor_repositories.repository() declaration contract rather than creating a second dependency inventory. Every redistributed direct or nested vendor component records:

• SPDX package name and exact version or commit;
• immutable download/source URL and archive SHA-256 already owned by the repository declaration;
• SPDX license expression and exact upstream license-file labels;
• applied GizOS patches;
• consuming Bazel targets or release-artifact relationships.

Nested dependencies with an independent version or license identity remain separate SPDX packages. A toolchain, SDK or system library not redistributed in a GizOS release is explicitly external and is not assigned packaged-file ownership.

Public release scope

The aggregate GizOS SBOM covers only artifacts selected by the current public Release workflow. Each released firmware/package asset receives a deterministic relationship to the subset of source components in its configured Bazel transitive graph. Compliance files are published as release sidecars and included in SHA256SUMS; this Issue does not change H2Loader package payload format to embed human-readable files inside a device image.

If the Release workflow later adds another public artifact class, it must provide the same graph/package manifest contract before that artifact enters the aggregate SBOM. Private downstream consumer artifacts are outside this repository's generator invocation.

SPDX and notices

The generator emits SPDX 2.3 JSON with a deterministic document namespace derived from immutable release identity, stable package ordering and explicit DESCRIBES/DEPENDS_ON relationships. Identical inputs produce byte-identical normalized output.

THIRD_PARTY_NOTICES.txt groups the unmodified upstream copyright/license text by component and exact revision in stable order. The SBOM and notice generator consume the same canonical component records; a component cannot appear in one output but silently disappear from the other.

Reconciliation and failure behavior

Reconcile canonical vendor metadata, Bazel transitive dependencies, firmware catalog entries, package manifests and assembled release assets. Release fails for a redistributed component with missing provenance/license data, a missing license file, a stale declared component, an undeclared package/runtime component, a checksum mismatch or any workspace/cache/credential path in generated evidence.

Components proven not to be redistributed remain external and do not create false package ownership. Exceptions to a known license expression must be explicit reviewed metadata; an unexplained NOASSERTION fails closed.

Test And Acceptance Criteria

Acceptance Criteria

• Every third-party component redistributed by a current GizOS release asset has canonical name, exact version/revision, source URL, integrity, SPDX license expression and license text.
• The release produces valid deterministic SPDX 2.3 JSON plus THIRD_PARTY_NOTICES.txt for the aggregate release and correct per-asset dependency relationships.
• //tools/bazel:firmware_release_bundle requires the compliance sidecars and includes them in release SHA256SUMS.
• Bazel dependency graphs, firmware catalog/package manifests and release contents reconcile without missing, stale or undeclared redistributed components.
• Generated evidence contains no credential, workspace, cache, runner-private or private Firmwares product path.
• Missing metadata/license text, integrity mismatch, undeclared component and stale notice fixtures fail before publication.
• Firmwares private product aggregation remains outside the GizOS implementation and documentation.

Validation

bazel mod deps --lockfile_mode=error
bazel test //tools/bazel/sbom:all //tools/bazel:release_bundle_test
bazel build //tools/bazel/sbom:release_spdx //tools/bazel/sbom:third_party_notices
make bazel-release RELEASE_SLICE=catalog RELEASE_VERSION=0.0.0
make guides-build
git diff --check

• Validate every generated SPDX document with an independent SPDX 2.3 validator.
• Rebuild from identical immutable inputs and compare normalized SBOM, notices and checksum bytes.
• Remove one license input, alter one vendor SHA-256, inject one undeclared release component and add one stale notice record; each controlled fixture must fail.
• Inspect a complete current Release workflow bundle and prove every published compliance sidecar is present in SHA256SUMS with no private path disclosure.