Status: 180.C.16.03 initial signed-manifest implementation.
Implementation date: 2026-04-23.
This plan adds the first Remote Host update contract: channel selection, signed update manifests, rollback-safe metadata, failed-update recovery steps, and adapter compatibility requirements for the Remote Host package, LaunchAgent, desktop helper, Blender add-on, and Unreal plugin. It does not claim that the later production app shell, Sparkle appcast, installer updater, or live rollback drill exists yet.
Sources Reviewed#
Local implementation references:
libs/oshun/shell-desktop/src/update-manager.tslibs/oshun/shell-desktop/src/types.tslibs/neith/integration-bellona/src/deployment-system/rollout-strategies.tslibs/neith/linux/crates/neith-update-agent/src/rollback.rsapps/bellona/remote-host/src/macos-packaging-plan.tsapps/bellona/remote-host/src/update-manifest.tsdocs/domains/bellona/extras/remote-control/macos-packaging-and-notarization-plan.md
External primary references reviewed:
- The Update Framework current specification: https://theupdateframework.io/specification/latest/
- Sparkle publishing documentation: https://sparkle-project.org/documentation/publishing/
- electron-builder auto-update documentation: https://www.electron.build/auto-update
Implementation Decision#
Remote Host now exposes a typed signed-manifest contract through
createRemoteHostUpdatePlan() and verifyRemoteHostSignedUpdateManifest(). The
contract is intentionally TUF-inspired instead of directly adopting Electron
updater metadata. Remote Host is not an Electron app today, and the macOS
packaging plan is Developer ID package based. Sparkle can later consume the same
package artifacts and channel policy once 180.C.26 delivers the native app
shell and installer/update runner.
The manifest signature is Ed25519 over stable canonical JSON (json-stable-v1).
The host verifies the signature with a trusted public key, then applies channel,
expiry, rollback, artifact, and adapter compatibility checks before accepting an
install or rollback action.
Channel Policy#
| Host channel | Eligible manifest channels | Intended use |
|---|---|---|
stable |
stable |
Production users and alpha release candidates |
beta |
stable, beta |
Pre-release operators with stable fallback |
canary |
stable, beta, canary |
Early staged rollout and package smoke validation |
internal |
stable, beta, canary, internal |
Release engineering and local signed drills |
A host rejects a signed manifest for any channel outside its eligibility set. Rollout percentage is represented in the signed payload so staged rollout decisions are auditable and cannot be silently changed outside the manifest.
Signed Manifest Requirements#
Every update manifest must include:
- schema version and monotonic
manifestVersion - release id, package version, build number, channel, rollout percentage, and expiry timestamp
- artifact entries for the Remote Host installer package, app bundle, LaunchAgent, desktop helper, Blender add-on, and Unreal plugin
- HTTPS artifact URLs, SHA-256 checksums, positive sizes, and signing notes
- adapter compatibility requirements for Remote Host, Blender add-on, Unreal plugin, and desktop helper
- rollback plan metadata, even when rollback mode is
none - Ed25519 signature metadata with key id and canonicalization mode
The host rejects expired manifests, unsupported schema versions, untrusted
signing keys, invalid signatures, non-HTTPS artifact URLs, malformed checksums,
missing release artifacts, missing adapter compatibility rows, and manifests
whose manifestVersion is not newer than the last trusted manifest.
Rollback Policy#
Rollback is an operational update, not a replay of old metadata.
To roll back from 0.2.0 to 0.1.0, release engineering must publish a new
signed manifest with a higher manifestVersion, rollback mode
operator-rollback or automatic-health-rollback, the previous release id, the
source release id, the rollback reason, and recovery steps. This prevents a
network attacker or stale cache from downgrading a host by replaying an old but
validly signed manifest.
Failed update recovery must preserve:
- macOS Keychain device identity and signed host token
- previous signed Remote Host package in the release cache
- previous LaunchAgent plist
- previous desktop helper binary
- previous Blender add-on archive
- previous Unreal plugin archive
- audit evidence for install, health check, rollback decision, and recovery result
Adapter Compatibility#
Each manifest declares the adapter versions and protocol commands expected by the release. The host validates the currently installed adapter versions before accepting the package. This prevents a package update from leaving Blender, Unreal, or desktop fallback in a partially updated state where the gateway can dispatch commands that the local adapter no longer supports.
Compatibility rows currently cover:
remote-hostblender-addonunreal-plugindesktop-helper
Browser support remains part of the broader Remote Host binary and does not yet ship as a separate adapter artifact.
Release Gate#
Before a Remote Host update can become MVP alpha evidence, the release job must record:
- signed update manifest verification
pkgutil --check-signaturefor the installer packagespctl --assess --type installfor the installer packagexcrun stapler validatefor the package- SHA-256 digest of every artifact referenced by the manifest
- rollback drill result using a new signed rollback manifest
- adapter compatibility validation for Blender, Unreal, and desktop helper
Unit tests currently validate the typed contract, cryptographic signature
verification, tamper rejection, replay/downgrade rejection, rollback as a new
manifest version, and adapter compatibility failures. Live signed update
delivery, Sparkle/appcast generation, package installation, LaunchAgent repair,
and a hardware rollback drill remain blocked until the production macOS app and
installer stages in 180.C.26.