Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ check:
python3 -m py_compile scripts/check-repo-availability.py
python3 scripts/install-packages.py --check packages/bluefin.toml
python3 scripts/verify-rpm-contract.py --check packages/bluefin.toml
python3 -m unittest discover -s tests
grep -qE 'reusable-build\.yml@(v1|[0-9a-f]{40} # v1)$' .github/workflows/build.yml
test -f Containerfile.kernel
bash -n scripts/install-ogc-kernel.sh
Expand Down
56 changes: 54 additions & 2 deletions docs/skills/package-contract.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: package-contract
version: "1.0"
last_updated: "2026-09-05"
last_updated: "2026-09-11"
id: package-contract
one_line_purpose: Maintain Bluefin package parity and Utah's overlay manifest.
entry_point: docs/skills/package-contract.md
Expand Down Expand Up @@ -37,10 +37,15 @@ policy for changing them.
addition to* or *instead of* the contract lives here. The full rules are in
the header comment of that file (cite it; do not move or copy it):

- `[gnome]` — GNOME 51 desktop contract Hummingbird does not ship.
- `[gnome]` — GNOME 51 desktop contract Hummingbird does not ship, with
major version assertions (`[gnome.major_versions]`).
- `[build]` — toolchain needed to build the pinned GNOME extensions
(`scripts/build-gnome-extensions.sh`).
- `[services]` — desktop services Bluefin adds on top of the server base.
- `[factory]` — Bluefin parity packages expected from the Utah package factory
rebuilds (`.hum1.bfin`).
- `[repositories]` — explicitly allowed runtime RPM repositories.
- `[supply_chain]` — provenance report path and release identity patterns.
- `[unavailable]` — Bluefin contract packages none of Utah's repositories
provide.

Expand Down Expand Up @@ -83,6 +88,15 @@ The pinned package image is an RPM repository, not a runtime dependency: its
contents are copied into the image so the package transaction is reproducible
and does not depend on a mutable mirror (`Containerfile` L41-44).

An explicit repository allowlist (`[repositories].allowlist`) in
`packages/utah.toml` restricts runtime repositories strictly to:
- `utah-packages`
- `public-hummingbird-x86_64-rpms`
- `nvidia-container-toolkit` (for nvidia flavors)

Any unapproved repository or any repository resolving from Fedora causes the
build contract check (`scripts/verify-rpm-contract.py`) to fail closed.

## Supply-chain download verification

Every executable release asset fetched during image or ISO composition is
Expand All @@ -91,6 +105,44 @@ before extraction or execution. `scripts/check-download-integrity.py` runs
in `just check` and pre-commit to statically enforce that no build recipe
resolves a mutable latest release or downloads unverified executables.

## Supply-chain contract and provenance attestation

Beyond package name presence, `scripts/verify-rpm-contract.py` enforces full
supply-chain integrity and NEVRA identity:

1. **GNOME 51 major version & release identity**: Core GNOME desktop contract
packages (`gnome-shell`, `mutter`, `gnome-control-center`, `gnome-session`,
`gnome-settings-daemon`, `gsettings-desktop-schemas`, `xdg-desktop-portal-gnome`)
must match required major version 51 (`[gnome.major_versions]`) and carry
factory/Hummingbird release identity (`.hum1.bfin` / `.hum`), failing if
any Fedora disttag (`.fc`) is detected.
2. **Factory parity package origin**: Bluefin parity packages expected from
factory rebuilds (`[factory].packages`) must carry the factory release
identity (`.bfin`, e.g. `.hum1.bfin`) and cannot silently resolve from
Hummingbird base or any other repository.

`[factory].packages` is a contract with the `utah-packages` factory repo,
not just this one: every name listed is a promise that `utah-packages`
rebuilds and publishes it. There is no shared CI between the two repos, so
if a package is dropped or renamed on the factory side, this check is the
only thing that will notice -- and it notices here, not there. Keep the
list in sync with what the factory actually ships, and link the tracking
issue for keeping the two repos' release-identity conventions in sync
once one exists.

The `.hum1.bfin` / `.hum` release-identity patterns themselves are not
hardcoded in the script -- they live in `[supply_chain].factory_release_pattern`
and `[supply_chain].hummingbird_release_pattern` in `packages/utah.toml`,
so a dist-tag convention change on either repo is a one-line data edit
there, not a code change here.
3. **Runtime repository allowlist**: The final image is verified to expose only
the explicitly allowed runtime RPM repositories; any enabled Fedora or
unapproved repository fails the build.
4. **Build provenance & NEVRA report retention**: A complete resolved
package-origin/NEVRA report is written to
`/usr/share/utah/package-provenance.json` recording package NEVRAs, source
RPMs, vendor, repository origin classification, and attestation status.

## Install and verify cannot disagree

`scripts/install-packages.py` records exactly what its run resolved to
Expand Down
102 changes: 102 additions & 0 deletions packages/utah.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@
# Sections:
# [gnome] GNOME 51 desktop contract Hummingbird does not ship
# [build] toolchain needed to build the pinned GNOME extensions
# [services] desktop services Bluefin adds on top of the server base
# [factory] Bluefin parity packages expected from the Utah package factory
# [repositories] explicitly allowed runtime RPM repositories
# [supply_chain] provenance and release identity policies
# [unavailable] Bluefin contract packages none of Utah's repositories provide
#
# On [multimedia_overrides], which Utah deliberately does not install:
Expand Down Expand Up @@ -48,6 +52,19 @@ packages = [
"xdg-desktop-portal-gnome",
]

[gnome.major_versions]
gnome-control-center = "51"
gnome-session = "51"
gnome-settings-daemon = "51"
gnome-shell = "51"
gsettings-desktop-schemas = "51"
mutter = "51"
xdg-desktop-portal-gnome = "51"
gtk4 = "4"
libadwaita = "1"
xdg-desktop-portal = "1"


[build]
# Build dependencies for scripts/build-gnome-extensions.sh.
#
Expand Down Expand Up @@ -82,6 +99,91 @@ packages = [
"tailscale",
]

[factory]
# Bluefin parity packages expected to be built and provided by the Utah package factory.
# These packages must carry the factory release identity (.hum1.bfin) and cannot silently
# resolve from Hummingbird or another repository.
packages = [
"adw-gtk3-theme",
"adwaita-fonts-all",
"alsa-firmware",
"alsa-tools-firmware",
"anaconda-live",
"containerd",
"ddcutil",
"distrobox",
"evtest",
"fastfetch",
"flatpak-spawn",
"fzf",
"gnome-ponytail-daemon",
"gnome-tweaks",
"google-noto-sans-cjk-vf-fonts",
"gum",
"gvfs-nfs",
"ibus-mozc",
"ibus-unikey",
"igt-gpu-tools",
"input-remapper",
"isomd5sum",
"just",
"libappindicator-gtk3",
"libayatana-appindicator-gtk3",
"libblockdev-btrfs",
"libblockdev-dm",
"libblockdev-lvm",
"libblockdev-mpath",
"libcamera-gstreamer",
"libcamera-tools",
"libratbag-ratbagd",
"libva-utils",
"livesys-scripts",
"make",
"mesa-libGLU",
"mozc",
"nautilus-gsconnect",
"openrgb-udev-rules",
"python3-gnome-ponytail-daemon",
"slitherer",
"squashfs-tools",
"switcheroo-control",
"waypipe",
"wireguard-tools",
"wl-clipboard",
"xdg-terminal-exec",
"xorriso",
"zenity",
]

[repositories]
# Runtime RPM repositories explicitly allowed in the composed image.
# Fedora or any unapproved repository enabled at runtime will fail verification.
allowlist = [
"utah-packages",
"public-hummingbird-x86_64-rpms",
"nvidia-container-toolkit",
]

[supply_chain]
report_path = "/usr/share/utah/package-provenance.json"
# These patterns encode the *current* dist-tag convention on each side. If
# utah-packages or Hummingbird ever change how they tag releases, update the
# pattern here rather than in scripts/verify-rpm-contract.py -- the two repos'
# release-identity conventions must move together, and this is the one place
# that should need editing when they do.
#
# The factory marker is `.bfin` ALONE, deliberately. Today every factory
# artifact is also tagged `.hum<N>`, so `.*\.hum\d*\.bfin.*` would match all
# of them -- but it would additionally REJECT a factory RPM tagged `.bfin`
# without a Hummingbird segment, reporting it as a "silent repository
# fallback" when it came from exactly where it was supposed to. That is a
# false accusation waiting for the first artifact that does not carry both
# tags. `.bfin` is what "came from the factory" means; `.hum<N>` is a separate
# fact with its own pattern below. Keep them separate.
factory_release_pattern = '.*\.bfin.*'
hummingbird_release_pattern = '.*\.hum\d*.*'


[unavailable]
# Packages Bluefin ships that none of Utah's repositories provide. Each entry
# MUST carry a tracking issue: this list is the documented parity debt, not a
Expand Down
Loading