Publishing a signed release channel (vendor and release engineers)

This page documents how a signed engine release is published to the update channel. It is the producer side of the trust model the customer-facing pages describe from the other end: the engine PULLS a signed channel from inside the customer’s account and verifies it, and the vendor never pushes code. It is written for a release engineer cutting a release the engine will accept, not for a customer, and it is operator-internal.

The tool described here, engine/tools/publish-channel.mjs, lives in the engine repository (versioned, tested by test/validate-publish-channel.ts, reviewable) but never in the shipped bundle: the deployable artefact is built from src/ alone, so only the verify side ships in the product. The publisher is the vendor’s private process, run on a release engineer’s own machine, and never something a customer runs. For how an account turns the channel on, read update channel activation; for how an applied update is verified, gated and rolled back, read applying an update from the channel.

What the publish tool produces

A publish run turns a version into the files the engine knows how to consume: the channel document, its detached signature, and the deployable bundle the channel points at; a release that carries the console adds a fourth, the self-describing console artefact. The signature and the hashes are computed with the engine’s own primitives, imported from the engine source, so the publisher and the verifier can never drift.

The tool builds the bundle by running Wrangler’s dry-run, which bundles exactly what a real deploy would push, locally, with no network and no deploy credential. It then hashes those bundle bytes with the engine’s own SHA-384 and writes the hash into the channel, so the value the engine recomputes at apply time matches the signed hash byte for byte. You can also hand it a bundle you built yourself with a Wrangler dry-run and have it ingest that instead.

This local-build path is the development shape of a publish, not the production one. A release customers will accept is published in ceremony mode from a CI-attested release tree, described below, which replaces --build and --bundle.

# Build the bundle locally, sign a channel that points at it, write all three files.
# Development shape: a production release uses --from-release-dir instead.
node tools/publish-channel.mjs --key-file ./release-signer.key --version 0.2.0 --build \
    --sequence 7 \
    --url https://update.example.com/engine-0.2.0.mjs \
    --out channel.json --out-sig channel.json.sig --out-bundle engine-0.2.0.mjs

The tool prints the channel JSON, the signature, the signer public key to pin, and a note on where to publish each file. A channel-only publish (no bundle) is possible for a notify-only release, but the safe-apply harness cannot download or verify an artefact the channel does not fully describe, so an in-console apply needs a bundle with a URL and a hash.

Multi-component releases

Channel schema v2 is additive. A v2 document carries a components map describing each component of the release, the engine as a worker module and the console as a static-assets bundle, while the engine-only artefacts[] list keeps being dual-written indefinitely, because every deployed pre-v2 engine selects its artefact from that list and ignores unknown fields. One publishing rule is absolute: a console artefact is never placed in artefacts[]. An old engine selects from that list by version string alone, so a console entry there could be chosen for the engine script and its hash would verify (it is the console bundle’s true hash); keeping the list engine-only is what makes that mistake impossible to publish.

The recommended version is the release version, and each component carries its own version. A component whose version already matches what a reader runs simply shows as up to date, so a console-only fix repeats the engine’s current version in the engine component and moves only the console’s. “Ship both at once” and “ship one alone” are therefore publishing decisions in one document, not different mechanisms, and every release stays one signed statement under the one pinned key.

The engine verifies the signature over the bytes it fetched, then parses those same bytes. It does not canonicalise or reformat the document before checking the signature. So the published file must be exactly the bytes that were signed.

This has one operational consequence worth stating plainly. Re-serialising or pretty-reformatting the channel document after signing breaks the signature, and the engine will refuse the channel with a verification failure. The tool emits a stable two-space-indented serialisation and signs exactly those bytes; publish that file verbatim, byte for byte.

The offline-signer discipline

The release-signer private key is offline and never deployed. This is the property that makes pull-not-push safe, and it is worth being precise about why.

The engine pins the release-signer public key in its configuration and verifies every channel against exactly that pinned key. The host that serves the channel is untrusted: a compromised channel host cannot substitute an unsigned document or one signed by a different key, because the engine checks the pinned signature and will not fall back to an unverified document. The trust is in the signature, not the host. Since the signing key never goes near the deployed engine or the channel host, compromising the running platform does not yield the ability to sign a malicious release.

The publish tool reflects that discipline in four ways worth listing.

• It lives outside the shipped bundle (repo-owned under engine/tools/, never built into the artefact), so the signing key and the signing code are never part of the deployed surface.
• It performs no deploy and no upload; in ceremony mode its only reads are the local release tree the engineer already downloaded, and cosign’s verification of the embedded Sigstore material.
• It imports the engine’s own signer derivation, hybrid signer and byte encodings, so the bytes it signs are exactly the bytes the engine verifies.
• It draws OS randomness for both seeds when generating a fresh keypair, and the generated private never leaves the machine: it is written only to a restricted key file or, if you ask, echoed once so you can persist it yourself.

The attested ceremony (dual-root releases)

A production release is published in ceremony mode, which makes the release dual-root: the offline hybrid key stays the one signature customers’ engines enforce, and the CI attestation set makes every release publicly falsifiable. The rule inside that mode is simple: the ceremony refuses to sign bytes CI did not attest.

Ceremony mode is entered by --from-release-dir (and --console-release-dir for a component release), and it is a choice the release engineer makes, not a state the tool infers. Nothing stops a --build publish from signing fresh local bytes, so the discipline that a production release is always published from an attested tree is a process rule, not a guard the tool applies on your behalf. What the tool does guarantee once you are in ceremony mode is that you cannot half-leave it: --from-release-dir refuses to be combined with --build or --bundle, --provenance-out-dir is mandatory, a missing cosign binary is a refusal rather than a skip, and a cross-component guard refuses a channel that mixes one attested component with one built locally beside it.

The flow per release tag:

1. CI builds the artefact deterministically on the signed tag (the release workflow verifies the tag signature against the signer roster committed on main), emits one canonical SHA256SUMS.txt and a release-facts.json carrying CI’s own identifiers (repository, commit, run id), cosign-signs every file keyless (logged to the public Rekor transparency log) and mints SLSA Build L3 provenance with the artefact digests as subjects.
2. The release engineer downloads the whole release tree (gh release download vX.Y.Z -D <dir>) and runs the publisher with --from-release-dir <dir> (and --console-release-dir for a component release). The tool re-derives every digest locally, checks the SLSA statement’s subjects and builder, and verifies the cosign bundles under the pinned release-workflow identity. Any failure, including a missing cosign binary, is a refusal before anything is signed.
3. The signed channel then embeds a per-component provenance block (commit, tag, repository, CI run, Rekor log index, and channel-relative attestation paths), so the offline signature transitively vouches for the provenance pointers: stripping or swapping them requires the pinned key.
4. --provenance-out-dir (required in ceremony mode) writes the sidecar set under provenance/<version>/ exactly where the signed paths point, plus release-record.json as the display mirror the console cross-checks. Publish every sidecar in the same sitting as the channel; a channel whose provenance paths return nothing is a published overclaim.
5. Every publish carries sequence and issuedAt inside the signed body (the tool refuses to sign without them unless the legacy escape hatch --allow-unsequenced is explicit). The first sequenced publish sets the anti-replay baseline for every fielded engine, so choose the first sequence deliberately; the sequence-state file lives beside the signing key and only advances after a self-verified emit.

What this buys, stated precisely: forging an update that customers’ engines accept still requires the offline hybrid key, exactly as before; forging one that also passes public scrutiny now additionally requires either compromising the release workflow identity or breaking the reproducible build. The two roots fail independently.

Risk class and customer-side dual control

A release declares a risk class, and that label drives whether the apply needs a second Owner on the customer side. The classes are routine, migration and breaking.

The safe default is the load-bearing part. An unlabelled release, or one carrying a value the engine does not recognise, is normalised to migration-class, never to routine. A release that needs a Durable Object migration is also forced to at least migration-class, since a migration is never routine. So the only way a release skips the second-owner approval is to be explicitly labelled routine and to need no migration; an old or garbled channel can never slip through as routine by omission.

The channel host

The channel host is a single static endpoint. The engine fetches the channel body from its configured URL and the detached signature from that same URL with a .sig suffix. Because the trust is in the pinned signature and not the host, the channel is served as two static files (the body and its signature) plus the artefact bytes each release points at, the engine bundle and, for a component release, the console artefact, from a public object store behind a custom domain. There is no worker and no billing coupling on the channel host.

The host hostname is the singular update.downpipes.io, per the locked decision and per the shipped UPDATE_CHANNEL_URL in wrangler.toml. Note the singular form: it is update, not the plural. The host is live: the vendor has stood it up and it serves the signed channel. The shipped config pins the signer and sets this URL, so the engine reports configured: true, and because a signed channel is now being served, the channel verifies under the pinned key.

Where this fits

• Update channel activation is the operator runbook for turning the channel on in an account: pinning the signer key and pointing the engine at the channel.
• Applying an update from the channel covers the consumer side: how a verified update is downloaded, hashed against the signed channel, canary-gated and auto-rolled-back.
• Update channel trust and rollback explains the pinned-signature trust model and the standalone rollback control in full.
• The command reference documents the in-account upgrade runbook the CLI prints, which never holds a standing deploy credential.
• Changelog and versioning explains the engine version line the channel’s recommended version is compared against.

Last updated 4 August 2026.