# Verify a bundle Check a bundle’s signature and files before installing, and understand common verification failures. Source: https://debark.dev/docs/trust/verifying --- 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](/docs/trust/signing). ## Verify a folder or archive ```bash 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](/docs/reference/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 ```bash 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](/docs/guides/automation) 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: ```bash 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.