"bgrpiimage-common", # apply-lib.sh, sourced by every apply.sh

"bgrpiimage-base",

"bgrpiimage-network",

"bgrpiimage-boot",

"bgrpiimage-can",

"bgrpiimage-unattended-upgrades",

# Carries the watchdog drop-in, the RTC services and the ALSA sink. Its

# config.txt counterpart already travelled in bgrpiimage-boot, so leaving

# this one out shipped half of every hardware feature: an update could roll

# out `dtoverlay=i2c-rtc` and never enable hwclock.service to go with it.

# No credential material - the payload is hardware.env plus generated conf

# files - and its EEPROM branch is gated on image context, so an update

# cannot arm a bootloader rewrite.

"bgrpiimage-hardware",

h = hashlib.sha256()

with path.open("rb") as fh:

for chunk in iter(lambda: fh.read(1 << 16), b""):

h.update(chunk)

"""Copy every allowlisted module's filesystem/root into one tree."""

root = staging / "root"

root.mkdir(parents=True)

for module in BUNDLE_MODULES:

if not gen._module_enabled(module, cfg):

continue

src = gen.MODULES_DIR / module / "filesystem" / "root"

if not src.is_dir():

continue

shutil.copytree(src, root, dirs_exist_ok=True)

"""Fail closed if a credential made it into the tree.

needles: list[tuple[str, str]] = []

for name in SECRET_ENV:

value = env.get(name, "")

if len(value) >= 6:

needles.append((name, value))

for demo in gen._KNOWN_DEMO_PASSWORDS:

needles.append(("known demo password", demo))

hits: list[str] = []

for path in sorted(staging.rglob("*")):

if not path.is_file():

continue

try:

text = path.read_text(encoding="utf-8", errors="ignore")

except OSError:

continue

for label, needle in needles:

if needle in text:

hits.append(f"{path.relative_to(staging).as_posix()} contains {label}")

variant = cfg["variant"]

base_image = cfg.get("base_image") or {}

root = staging / "root"

# Which container runtime this bundle was generated for. base_image_sha256

# already draws the line between a config update and an OS update, but it

# tracks the upstream Raspberry Pi OS and has no reason to move when only

# the runtime does - so a Docker-to-Podman migration is invisible to it.

# A bundle built before this field existed carries none of it, and the

# updater treats that silence as "assume Docker", because every release

# before v0.14.0 was.

if (cfg.get("podman") or {}).get("enabled"):

runtime = "podman"

elif (cfg.get("docker") or {}).get("enabled"):

runtime = "docker"

else:

runtime = "none"

return {

"bundle_format": BUNDLE_FORMAT,

"dist": "bgrpiimage",

"variant": variant["name"],

"version": variant.get("version", "0.0.0"),

"description": variant.get("description", ""),

# The line between a config update and an OS update. A device whose

# /etc/bgrpiimage-release records a different base image is running a

# different Raspberry Pi OS than this bundle was generated against,

# and applying it would be guesswork.

"applies_to": {

"variant": variant["name"],

"base_image_sha256": base_image.get("sha256", ""),

"base_image_url": base_image.get("url", ""),

# Devices flashed before the identity contract carry none of the

# fields the refusals need, so they are told to reflash instead.

"min_apply_contract": gen.APPLY_CONTRACT_VERSION,

# Purely additive and optional: bundle_format does not move for

# this. An updater from before this field existed simply never

# reads it, which is exactly the fallback the gate is built for.

"container_runtime": runtime,

},

"modules": [

m for m in BUNDLE_MODULES

if gen._module_enabled(m, cfg)

and (gen.MODULES_DIR / m / "filesystem" / "root").is_dir()

],

"files": [

{

"path": f.relative_to(root).as_posix(),

"sha256": _sha256_file(f),

"size": f.stat().st_size,

}

for f in files

],

"""Sign the manifest with the release key.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

from cryptography.hazmat.primitives import serialization

key = serialization.load_pem_private_key(key_pem, password=None)

if not isinstance(key, Ed25519PrivateKey):

raise SystemExit("error: the signing key is not an Ed25519 key")

"""The key comes from the environment in CI, or a file locally.

pem = os.environ.get("BGRPIIMAGE_SIGNING_KEY", "").strip()

if pem:

return pem.encode("utf-8") + b"\n"

local = ROOT / ".secrets" / "bgrpiimage-recovery.key"

if local.is_file():

return local.read_bytes().replace(b"\r\n", b"\n")

signature: bytes | None = None) -> bytes:

"""Deterministic tarball: same commit in, same bytes out.

payload = json.dumps(manifest, indent=2, sort_keys=True).encode("utf-8") + b"\n"

out.parent.mkdir(parents=True, exist_ok=True)

# tarfile's "w:gz" writes the current time into the gzip header, so two

# builds of the same commit produced different checksums - which defeats

# the point of publishing one. Drive the GzipFile directly with mtime=0

# and an empty filename field so the container is a pure function of its

# contents.

with open(out, "wb") as raw, gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as gz, tarfile.open(fileobj=gz, mode="w", format=tarfile.PAX_FORMAT) as tar:

info = tarfile.TarInfo("manifest.json")

info.size = len(payload)

info.mtime = 0

info.mode = 0o644

tar.addfile(info, io.BytesIO(payload))

if signature is not None:

sig_info = tarfile.TarInfo("manifest.json.sig")

sig_info.size = len(signature)

sig_info.mtime = 0

sig_info.mode = 0o644

tar.addfile(sig_info, io.BytesIO(signature))

root = staging / "root"

for path in sorted(p for p in root.rglob("*") if p.is_file()):

rel = path.relative_to(staging).as_posix()

info = tar.gettarinfo(str(path), arcname=rel)

info.mtime = 0

info.uid = info.gid = 0

info.uname = info.gname = "root"

info.mode = 0o755 if path.suffix == ".sh" or "sbin/" in rel else 0o644

with path.open("rb") as fh:

tar.addfile(info, fh)

ap = argparse.ArgumentParser(description=__doc__)

ap.add_argument("config", type=Path, help="path to variant JSON config")

ap.add_argument("--env-file", type=Path, help="optional .env file (KEY=VALUE lines)")

ap.add_argument("--out", type=Path, default=Path("dist"), help="output directory")

ap.add_argument("--unsigned", action="store_true",

help="build without a signature (devices will refuse it)")

args = ap.parse_args()

# Same precedence as generate.py's main(): the process environment wins,

# the file only fills gaps. Duplicated rather than imported because that

# parsing lives inside generate.main() and pulling it out is a refactor

# this script does not need to force.

import os

env = dict(os.environ)

if args.env_file and args.env_file.exists():

for line in args.env_file.read_text(encoding="utf-8").splitlines():

line = line.strip()

if not line or line.startswith("#") or "=" not in line:

continue

k, v = line.split("=", 1)

env.setdefault(k.strip(), v.strip().strip('"').strip("'"))

raw = gen.load_variant(args.config)

cfg = gen.resolve_tree(raw, env)

name = cfg["variant"]["name"]

version = cfg["variant"].get("version", "0.0.0")

# Guard against packing a stale tree. The renderer writes this file on

# every run, so a mismatch means generate.py has not been run for this

# variant at this version and the payload on disk belongs to something

# else entirely.

variant_cfg = gen.VARIANTS_DIR / name / "config"

if not variant_cfg.exists():

print(f"error: {variant_cfg} missing - run generate.py for this variant first",

file=sys.stderr)

return 1

if f"DIST_VERSION='{version}'" not in variant_cfg.read_text(encoding="utf-8") \

and f"DIST_VERSION={version}" not in variant_cfg.read_text(encoding="utf-8"):

print(f"error: {variant_cfg} was rendered for a different version than {version}",

file=sys.stderr)

return 1

with tempfile.TemporaryDirectory() as tmp:

staging = Path(tmp)

files = stage(cfg, staging)

if not files:

print("error: nothing staged - has the variant been rendered?", file=sys.stderr)

return 1

hits = scan_for_secrets(staging, env)

if hits:

print("error: refusing to build a bundle containing credentials:", file=sys.stderr)

for h in hits:

print(f" {h}", file=sys.stderr)

return 1

manifest = build_manifest(cfg, staging, files)

# Sign the exact bytes that go into the archive, so the signature and

# the manifest cannot drift apart through a re-serialisation.

payload = json.dumps(manifest, indent=2, sort_keys=True).encode("utf-8") + b"\n"

key_pem = None if args.unsigned else load_signing_key()

if key_pem is None and not args.unsigned:

print("error: no signing key. Set BGRPIIMAGE_SIGNING_KEY (the PEM itself, "

"as CI does) or keep .secrets/bgrpiimage-recovery.key locally.\n"

" Pass --unsigned only for a bundle no device is meant to apply.",

file=sys.stderr)

return 1

signature = sign(payload, key_pem) if key_pem else None

stem = f"bgrpiimage-{name}-v{version}"

tar_path = args.out / f"{stem}.confbundle.tar.gz"

write_tar(staging, tar_path, manifest, signature)

digest = _sha256_file(tar_path)

(args.out / f"{stem}.confbundle.tar.gz.sha256").write_text(

f"{digest} {tar_path.name}\n", encoding="utf-8"

)

# Published beside the bundle so `update --check` can answer without

# downloading it.

(args.out / f"{stem}.bundle.manifest.json").write_bytes(payload)

if signature is not None:

# Sidecar for the standalone manifest, so `update check` can verify

# what it reads without pulling the whole bundle.

(args.out / f"{stem}.bundle.manifest.json.sig").write_bytes(signature)

size_kb = tar_path.stat().st_size / 1024

print(f"{tar_path} ({size_kb:.1f} KB, {len(manifest['files'])} files, "

f"{len(manifest['modules'])} modules)")

print(f" sha256 {digest}")

print(f" signed {'yes' if signature else 'NO - devices will refuse this bundle'}")