Verify a bundle

Run debark verify after copying a bundle to the target. It checks the bundle without installing packages.

You need the builder’s public key from a trusted source. The examples use operator.pub from Sign a bundle.

Verify a folder or archive

debark verify ./bundle --key operator.pub

You can pass a .debark.tar.zst archive directly, without extracting it yourself.

A successful check exits with code 0. A verification failure exits with code 4 and lists the problems. debark install repeats these checks before installation, even if you already ran verify.

Choose the verification keys

Option	Use
--key FILE	An Ed25519 public key file. Repeat for multiple keys.
--keyring DIR	A directory of trusted Ed25519 .pub files. Repeat for multiple directories.
--gpg-keyring FILE	A GPG keyring containing the expected public key for a GPG-signed bundle.

For defaults, set verify_keys or verify_keyring_dirs in the configuration. Their environment variables are DEBARK_KEYS and DEBARK_KEYRING_DIRS.

A key path inside the bundle is refused. Obtain the key independently; moving a key supplied by an unknown sender outside the folder does not make it trustworthy.

What gets checked

Verification checks that:

• The manifest and signature documents are readable and consistent.
• At least one signature verifies against a supplied trusted key.
• Each listed file has the expected type, size, and SHA-256 checksum.
• The bundle contains no unexpected files.
• The repository metadata, lock file, and snapshot match their recorded checksums.

Problems with the manifest or signature can stop verification early. Once file checking starts, multiple file problems can appear in one report.

Read a JSON report

debark verify ./bundle --key operator.pub --json > verify.json

The useful fields are:

Field	Meaning
ok	The bundle passed the checks required by this invocation.
signed	A signature verified against a trusted key. File checks must pass too, so read it together with ok.
signatures	Results for individual signatures, including valid and trusted.
problems	Failed checks, with a problem kind and relevant details.

For a script that requires a signed bundle, run without --allow-unsigned, check the command’s exit code, and require both ok and signed. See Automate builds for a complete example.

Common failures

Problem	What to do
Missing or invalid signature	Confirm the expected public key, then ask the builder for a signed bundle if needed.
File size or checksum mismatch	Copy the original bundle again and verify the new copy.
Unexpected file	Use a clean copy of the bundle. Keep your notes and reports outside it.
File is a link or another unexpected type	Check the copy or extraction method.
same-media-key-refused	Use a key obtained independently and stored outside the bundle.

Do not edit the manifest or remove its checks to make verification pass. Those checks are what connect the files to the signed build.

Intentionally unsigned bundles

--allow-unsigned accepts a bundle without a valid signature:

debark verify ./bundle --allow-unsigned

File checks still run, but the command no longer requires proof of the builder’s identity. It is not a repair for signature errors; some signature failures still stop verification.