Verifying a bundle

For security reviewers, and anyone deciding whether to trust a bay's rule set. You do not need this page to integrate a device.

You do not have to take SGA's word for what is in the standard you are running.

A bundle arrives like a sealed envelope. The seal tells you who sent it. It tells you nothing about what is written on the paper inside. Those are two different questions, and they need two different checks:

Neither is worth much alone. A valid signature on altered content is still altered content — it only tells you who altered it. And content that matches the public specification, with nothing signed, tells you nothing about where the file came from. Run both. Together they take about a minute.

1. Does it verify?#

sgabundle verify sga-bundle-2026.09.1.tar.gz

Inside every bundle is a manifest.json listing each file with its digest — a short fingerprint computed from the file's contents, which changes if any byte of it changes. Beside it sits manifest.sig, a signature: proof that whoever holds SGA's private key saw those exact manifest bytes and vouched for them.

So the check runs in two moves. The signature is checked against the manifest, and then each file is checked against the fingerprint the manifest claims for it. Alter a file and its fingerprint no longer matches; alter the manifest to cover for that, and the signature no longer matches.

The key it checks against is pinned — built into the program itself rather than fetched from anywhere, because a key a program can be told about is a key an attacker can tell it about. To see which keys the copy you are running trusts:

sgabundle pinned

Build the tool yourself if the answer matters. If you use our program, with our key built into it, to check our file, the only thing you have really established is that we are internally consistent. sgabundle and the bundle package underneath it are in the engine repository — the same code that verifies bundles on a live bay. Once the engine's source is published you can read it and build it, and then the check is yours rather than ours. Until then, step 2 does not depend on our tools at all.

2. Does it reproduce?#

A bundle is generated from the field catalog rather than assembled by hand, and the build is deterministic: the same inputs always produce a byte-for-byte identical file. Nothing that would ordinarily vary between two builds — the order files are stored in, timestamps, which user ran it — is allowed to leak in.

That means you can build the bundle yourself from the public specification and check, byte for byte, that ours contains the same thing.

# your copy of the SGA-OIS repository, at the bundle's version
cd sga-ois
python3 build/bundle.py --reproduce /path/to/sga-bundle-2026.09.1.tar.gz

Python 3 and the repository, nothing else. No packages to install and no network access while it runs. It rebuilds from your copy of the source and compares file by file, naming any that differ.

Two things to get right:

• Use the version of the source the bundle was built from. The repository moves on; a later version of the source legitimately produces a different bundle, and the tool cannot tell that apart from tampering. It says so rather than guessing, so a mismatch is more often the wrong source version than an attack.
• The issue date is an input, not today's date, and --reproduce reads it out of the bundle's own manifest. A build that stamped itself with the current time could never reproduce anything.

The signature file is left out of the comparison. It is not reproducible and is not meant to be — checking it is step 1's job.

Why reproduction is the stronger check#

Verifying a signature answers who. It cannot answer what, because a signing key signs whatever it is pointed at.

Reproduction answers what, without relying on us at all. A bundle whose contents were altered does not reproduce — and that stays true even if the alteration were signed with SGA's own key. Change a validation limit, recompute the fingerprint in the manifest so everything agrees, sign the result, and you get a bundle that passes every signature check perfectly. It still does not survive a rebuild.

That is the intended division of labor. We hold a signing key, so you have to trust us about where a bundle came from. We do not ask you to trust us about what is in it.

What these checks do not cover#

• How SGA protects its signing key is a claim about our process, and no command proves a claim about a process. What we commit to, and what we publish versus keep internal, is in Governance. Reproduction is what stops that mattering as much as it otherwise would: the worst a compromised signing process can produce is a bundle that fails to reproduce.
• Whether the standard itself is any good is not a cryptographic question. The specification, the schemas and the catalog are public and open to review, which is the only real answer to it.
• Whether your engine program is genuine is a question for your operating system, not for this standard. Check the platform signature on whatever you downloaded, or build it from source.

If a check fails#

Treat a bundle that does not verify, or does not reproduce, as one you do not have. An engine that cannot verify a bundle keeps the one it already had and carries on — a bundle problem must never stop a round (04 §3).

If you think a published bundle is wrong, tell us before assuming the worst. Include the bundle version, which version of the source you built from, and the file-by-file output.