.zip verification

Availability: CLI v0.1.6 and the staging API. Older CLI releases may lack the required signed-upload flow. Production availability is not implied.

vapour publish checks the build zip on your computer before anything is uploaded, signs it, and the server checks it again. It protects players and the platform from broken or hostile build archives. It is static heuristic analysis, not an antivirus. It reads the zip without extracting it to disk, looks at at most the first 4 MiB of each file, and never executes anything. It cannot prove a build is safe. Minified engine JavaScript is not flagged for being minified.

How it works

1. Pack. The CLI zips build.dir, or takes your prebuilt .zip.
2. Local scan. The CLI statically analyzes the zip. Findings are error (upload is cancelled, nothing is sent, no version number is used) or warn (printed, upload continues).
3. Hash and sign. The CLI computes the SHA-256 of the exact zip bytes it will upload and writes a signed attestation at .vapour/build.zip.attestation.json.
4. Local verification. publish verifies the signed, exact ZIP bytes before uploading. This is the same local signature and hash check as vapour verify.
5. Upload gate. The server requires the attestation as part of the publish request. It independently checks the signature, registered developer key, SHA-256 and ZIP size before storing any build or version. Missing attestations return HTTP 400 verification_required; forged, mismatched or wrong-key attestations return HTTP 400 verification_failed. Malformed JSON, duplicate or oversized attestations return HTTP 400 invalid_upload.
6. Background scan. After accepting a verified upload, the server scans the ZIP independently. It records a verification status for the version: pending while the check is queued, then verified or rejected.
7. Verify later. Anyone with the zip and the attestation can check them offline. With --remote, the CLI also compares the hash with the one the server recorded for that version and shows the server status.
8. Dashboard. The "Your games" list shows a .zip verification column beside a review badge. See Review and approval.

Each version records a verification status: pending, verified, rejected or unverified.

Rejection reasons you can see on the dashboard: bad_signature, hash_mismatch, size_mismatch, bad_key_id, bad_key, unsupported_version, unknown_key, bad_attestation, or any scan code.

unknown_key means the signature was valid but the key was not yours: the first valid key a developer account uses is remembered, and a zip signed by a different key on the same account is rejected. If you lose your signing key, ask the platform team to reset the remembered key.

What the scan checks

Commands

vapour scan

Scan without uploading. The path is a .zip or a folder; the default is build.dir.

vapour scan                        # scans build.dir
vapour scan ./my-game.zip          # scans a prebuilt zip
vapour scan --dir ./games/my-game  # scans another game directory
vapour scan --json                 # machine-readable findings

Exit status is 1 if any error finding exists. Example output:

$ vapour scan ./build/my-game.zip
Scanned 143 files (12.4 MiB packed, 40.1 MiB unpacked)
  error native_extension [win/redist/msvcp140.dll]: File has a ".dll" extension, which does not belong in a web bundle.
  warn  nested_archive [cutscenes.tgz]: Entry looks like a nested archive; publish bundles should contain flat web files.
error: build rejected: 1 problem(s) found in the zip. Nothing was uploaded and no version number was used. Fix them and publish again (see the docs: games/zip-verification)

scan checks only. It does not write an attestation; only vapour publish writes .vapour/build.zip.attestation.json.

vapour verify

Check a zip against its attestation, offline or against the server.

vapour verify <zip>                       # attestation defaults to <zip> with .attestation.json appended
vapour verify <zip> --attestation <file>  # explicit attestation path
vapour verify <zip> --remote              # also compares the hash the server recorded
vapour verify <zip> --remote --dir ./games/my-game --version 0.2.0
vapour verify <zip> --json

Without --attestation, the CLI looks for <zip> with .attestation.json appended, then .vapour/build.zip.attestation.json. --remote needs a login; with --version <semver> it compares the server's recorded SHA-256 and status for that version. Exit status is 1 on any mismatch, bad signature, or server status other than verified. Example output:

$ vapour verify my-game.zip
OK: signature valid, SHA-256 9d1e…aa7b matches (key 6f0b1c2d3e4f5a6b, scan pass)

$ vapour verify my-game.zip --remote --version 0.2.0
OK: signature valid, SHA-256 9d1e…aa7b matches (key 6f0b1c2d3e4f5a6b, scan pass)
OK: the server recorded the same hash and marked the version verified

When the server status is not verified, --remote prints the status and exits with status 1, for example the server marked version 0.2.0 as "pending", as "rejected" or as "unverified". When the hash differs it prints the server recorded SHA-256 … for version …, but your zip is ….

vapour publish

publish runs the scan, signing and local verification automatically. There is no flag to skip the scan. --dry-run scans and signs but uploads nothing; it writes the attestation exactly like a real publish:

vapour publish --dry-run --version 0.2.0 --notes "Dry run"

If the scan reports errors, publish stops before authentication and no version number is used. After the upload, publish prints that server verification is pending and tells you to run vapour verify --remote --version <v> <zip> to see the result. The new version is not live until an admin approves it; see Review and approval.

--experimental-chunks remains available for a local dry run, but real chunk uploads are blocked until they can supply an attestation. Use ZIP publishing. See Publish and verify a build for the rest of the flow.

Attestation file

The CLI writes .vapour/build.zip.attestation.json next to the build:

Signing key

The key is created on first use at ~/.config/vapour/signing.key, mode 0600, honoring XDG_CONFIG_HOME. It signs every attestation your machine produces.

• Never share it or commit it to a repository.
• Lost: do not just re-create it. The first valid key a developer account uses is remembered and a zip signed by a different key is rejected with unknown_key. Ask the platform team to reset the remembered key.
• Leaked: tell the platform team.

Dashboard

The developer dashboard "Your games" list has a .zip verification column, shown beside a review badge. It shows the status and the first 12 characters of the SHA-256.

The zip check is not the whole story: every version still waits for an admin review before it is playable. See Review and approval.

Troubleshooting

Limits and honesty

• The scan is a heuristic. It lowers risk; it does not prove a build is safe. It reads at most the first 4 MiB of each file and never executes anything.
• A signature shows who produced the zip and that it was not changed since. It says nothing about whether the content is safe.
• The platform scans again. The local scan is not the last word.
• Statuses verified and unverified say how the archive was checked, not how good the game is.

For the upload flow, see Publish and verify a build. For every flag of the CLI, see the CLI command reference. For what a web build must contain, see Web export requirements.