GUIDES · 13

Verify integrity.

Every tebako artifact carries a Secure Hash Algorithm 256-bit (SHA-256) anchor, verification happens at fetch and install time and never per run, and any signed artifact is verified strictly.

The anchor: the .sha256 sidecar.

Next to every cached artifact sits a .sha256 sidecar, which holds the value the artifact was verified against when it landed. The sidecar is the trust anchor: its presence means verified at install. Runs never re-verify artifacts, which is what keeps each run fast.

What installation verifies.

tebako install downloads the payload to a temporary location, hashes it, compares the digest against the registry-published SHA-256, and only then renames it into place — read-only, with its sidecar beside it. A mismatch aborts with exit 70 and installs nothing; a partial install is invisible by construction.

The same verification happens for runtimes on first run, and for registry indexes on refresh. A registry added with a ?sha256= pin is verified on every refresh, not only on the first.

A manual digest check.

$ shasum -a 256 acme-fonts-2.1.0.tfs    # macOS
$ sha256sum acme-fonts-2.1.0.tfs          # Linux

The digest is compared against the value the publisher printed at publish time; that value is mirrored into the registry index and into the SHA256SUMS file on the release.

Re-verification with tebako inspect.

$ tebako inspect ./myapp                  # kind, slots, trust lines
$ tebako inspect --verify ./myapp           # re-run the checks now
$ echo $?
0

inspect auto-detects a package (trailer present) versus a bare image. --verify exits 0 on pass, or a named failure: 65 malformed · 70 SHA-256 mismatch · 71 signature invalid (or unsigned under TEBAKO_REQUIRE_SIGNED=1) · 72 trust failure, which means the key is not in the operator’s trusted set. --require-signed implies --verify and treats unsigned as a failure.

$ tebako-pkg validate ./myapp                # package trailers; adds 77 (era mismatch)
$ tfs info --verify ./acme-fonts-2.1.0.tfs     # bare images

Signing artifacts.

$ tebako-pkg sign ./acme-fonts-2.1.0.tfs

On first use this generates the press-local key under $TEBAKO_HOME/keys and registers its public half automatically. The output is a detached signature — acme-fonts-2.1.0.tfs.asc — plus a signed SHA256SUMS. --key <keyid> or --key-file <path> selects a different key, and --no-sums skips the sums file. Recipients verify with:

$ tebako-pkg verify --key-file ./acme-press.pub ./acme-fonts-2.1.0.tfs

Note	The flag is `--key-file`. The tool’s usage line currently prints `--keyring`; the parser accepts `--key-file` only.

Hardened environments.

Setting TEBAKO_REQUIRE_SIGNED=1 makes unsigned artifacts fail closed — exit 71 — at fetch and at install. Without the variable, unsigned remains a first-class case: a loud warning and a journal entry are recorded, and the run proceeds.