Skip to content
Cloudhal
Menu
News

Install bytes you can check: every Cloudhal release is now signed

Signed statements, build attestations, immutable releases and expiring key lists: what the last two years of supply-chain attacks taught us, and how to verify a Cloudhal release yourself.

Install bytes you can check. A release card for Cloudhal v0.10.1, marked Immutable, with four passed checks: signature, build attestation, key list and yank list, and the chain tarball to manifest.json to release-statement.json.
Illustration: Cloudhal
On this page
  1. Why releases are a target
  2. What a release contains
  3. How a release gets signed
  4. What it protects against, and what it doesn't
  5. Keys that expire, and a list that can only take trust away
  6. Why there is no soft-fail
  7. Install a release you can check
  8. Questions

When you update a website platform, you run code someone else built, on a machine that holds your keys and your content. That makes the update path one of the most valuable targets in open source, and the last two years proved it more than once. Since v0.9.0, every Cloudhal release ships as a signed bundle: the exact bytes to deploy, a signed statement that pins every one of them, and a build attestation that ties them to the commit and workflow that made them. This post explains what that protects against, what it doesn't, and how to check a release yourself.

23K+repositories used tj-actions/changed-files when its tags were movedMarch 2025
2B+weekly downloads behind the 18 npm packages hijacked by phishingSeptember 2025
0ways to install a Cloudhal release that fails a checkNo soft-fail, no override

Why releases are a target

These incidents are public and well documented. None was caused by broken cryptography: each one went through the gap between the code people reviewed and the bytes people installed.

Four supply-chain incidents and the gap each one used
WhenWhat happenedThe gapIn Cloudhal's release path
Mar 2024xz Utils: the step that activated a backdoor in 5.6.0 and 5.6.1 was only in the release tarballs, not in the Git repositoryRelease files built by hand, apart from the reviewed sourceThe bundle is built in CI from the tagged commit, and an attestation names that commit and workflow
Mar 2025tj-actions/changed-files: a stolen bot token let attackers point most version tags at a malicious commitTags and assets could be moved after publicationImmutable releases: tags and assets cannot change once published
Sep 2025chalk, debug and 16 more npm packages republished with crypto-stealing code after a maintainer was phishedOne account could publish new bytes under trusted namesPublishing needs no stored token, and the signature needs a reviewed, separate job
Sep 2025Shai-Hulud: a worm stole npm tokens from developers and republished itself into their packagesLong-lived publish tokens on laptops and in CInpm trusted publishing (OIDC), no long-lived npm token

Sources: Andres Freund's disclosure of the xz backdoor, CISA's alert on tj-actions/changed-files, Check Point on the npm phishing compromise and Krebs on Security on Shai-Hulud.

The platforms moved too. npm made trusted publishing with OIDC generally available in July 2025, and GitHub made immutable releases generally available in October 2025. Cloudhal uses both. Signing is the layer on top: it lets anyone who downloads a release check, offline and without trusting GitHub, that the bytes are the ones the project meant to ship.

What a release contains

Each release from v0.9.0 on carries the same set of files, all attached while the release is still a draft:

Assets of a signed release
FileWhat it is
cloudhal-release-<v>.tar.gzThe built site and admin Workers and the standard theme's static assets, in a deterministic tarball
manifest.jsonEvery part by path, size and SHA-256, plus what a deployer must know first: feature levels, migrations, whether rolling back past it is safe
release-statement.jsonA small document (at most 4 KB) that pins the manifest and the tarball by hash, for this version and commit
release-statement.sigA 64-byte Ed25519 signature over the statement's exact bytes
cloudhal-release-<v>.sigstore.jsonThe build-provenance attestation: which workflow, on which commit, produced these files
keys.json, yanked.json (+ .sig)Snapshots of the signed key list and yank list at release time (from v0.10.0)

The project key signs exactly one kind of file: the statement. Everything a deployer uploads is covered through it, because the statement pins the manifest and the manifest pins every file.

How a release gets signed

Building and signing happen in separate jobs that never share a secret. Pick a step:

Step

Build and attest. A reusable workflow checks out the release commit, builds the standard starter exactly as cloudhal deploy would, and writes the tarball, the manifest and the unsigned statement. It holds no secret. GitHub's attestation action then records which workflow built these files from which commit.

bundle-build.yml
  • Permissions: read the repo, write an attestation
  • Frozen lockfile
  • Refuses a part that contains a deploy secret
  • Output: 3 files + Sigstore bundle

We describe this as isolating the signing key from the build, with provenance produced by the building workflow. We don't claim a formal SLSA build level until the build platform's own requirements are assessed.

What it protects against, and what it doesn't

A consumer that checks both the signature and the attestation has two independent factors. Pick a threat to see what stops it:

Threat
Stopped by the second factor

The thief can sign, but cannot make GitHub attest that bundle-build.yml built those bytes on main. cloudhal deploy --release checks both. The key is then revoked through the yank list at once, and through the root-signed key list within days. A verifier that only checks signatures, such as a deployer running inside a Worker, relies on the key alone until it is revoked.

Keys that expire, and a list that can only take trust away

A signature is only as good as the answer to "which keys do I trust today?". Cloudhal answers it with three keys and two signed lists:

Keys and what each may sign
KeySignsKeptLifetime
Rootkeys.json onlyGenerated offline, encrypted; one sealed copy in a private repo, one offline; passphrase kept apartUsed at the yearly rotation or in an emergency
Release (cloudhal-release-2026a)release-statement.json onlySecret of one protected GitHub environment with a required reviewer2026-11-12 to 2027-11-12; the successor is listed 120 days ahead
Yank (cloudhal-yank-2026a)yanked.json onlyIts own protected environment, main onlyReplaced by the root, never overlapped

Both lists are served from cloudhal.dev/.well-known/cloudhal/, and both expire: keys.json within 13 months, yanked.json 30 days after each weekly signing. The merge rule is reduce-only: a list can revoke a key, narrow its window or withdraw a version, but nothing in either list can add a key you don't already pin. Adding a key stays a reviewed change on your side.

Why there is no soft-fail

The design takes one lesson from WordPress. WordPress 5.2 started signing updates with Ed25519 in 2019, with a verification key that expired on April 1, 2021, and it let updates through when a check failed, because the feature was still experimental. In June 2024 a core change turned signature verification off for core, plugin and theme updates until signing is fully in place on wordpress.org. Rolling out verification gently is a reasonable choice for a project of that size. It also shows how a check that is allowed to fail stops protecting anyone.

So every Cloudhal consumer refuses: an unknown, expired or revoked key, a list that cannot be fetched or has expired, a version that does not match the request. There is no override flag for any of these.

Install a release you can check

cloudhal deploy --release installs the signed standard theme of the CLI's own version instead of building your project. Your content, config and secrets still come from the project.

npx cloudhal deploy --release

To install another version, run that version of the CLI:

npx @cloudhal/cli@0.10.1 deploy --release

Before it uploads anything, it fetches and verifies the key and yank lists, checks the signature, the tarball's digest and the build attestation, and checks that your theme files equal the starter the bundle was built from. Its memory of the lists lives in ~/.cloudhal/release-trust.json.

Download a release's assets, then check the attestation with the GitHub CLI:

gh attestation verify cloudhal-release-0.10.1.tar.gz \
  --repo cloudhal-dev/cloudhal \
  --signer-workflow cloudhal-dev/cloudhal/.github/workflows/bundle-build.yml

The public release key and its fingerprints are in release-signing-keys.md.

@cloudhal/release-verify is the one verifier the CLI and the release scripts use. It runs on Workers, Node and in browsers with WebCrypto, so a host can verify a bundle where it deploys it:

const release = await verifyRelease({
  request: { version: "0.10.1" },
  statement, signature, manifest,
  tarball: () => stream,
  planVersion: 1,
});

Two flags, never implied

  • `--allow-single-factor` continues when the attestation cannot be checked (no `gh`), on the signature alone, and says so. A failed attestation is always a refusal.
  • `--discard-local-theme` deploys the official theme even though your theme files differ, after listing every file that will not be deployed. It deletes nothing on disk.
  • Neither flag is ever turned on for you, not in CI and not in non-interactive runs.

Questions

Which versions are signed?

v0.9.0 and later carry a bundle and a signature. From v0.10.0, each release also attaches the signed key list and yank list. v0.8.0 and older have no bundle and can never gain one, because their releases are immutable.

Do I have to use deploy --release?

No. cloudhal deploy still builds your project, and it is what you use for a custom theme. --release is for installing or updating the standard theme without a local build.

Will Cloudhal update my site on its own?

No. The project's tools never install a bundle automatically. A security release is marked as such in its manifest so tools can highlight it; installing it stays your decision.

What happens if cloudhal.dev is down?

deploy --release refuses, and your running site is not affected. It never falls back to an older cached list, because an attacker who blocks the site could otherwise roll trust back.

Where is the signing key kept?

In one protected GitHub environment with a required reviewer, readable only by the signing job. Moving it into a cloud KMS is planned for when there is a second maintainer, or at once if the secret is ever exposed.

The full design, including the formats, limits and the reasoning behind each choice, is in RFC-0046. Every release is on the releases page.

This post was drafted by an agent through this site's MCP server, from the repository's design documents and the public sources linked above, and a person approved it before it went live.