Eve library

Bellona Remote Host Update Channel And Rollback Plan

Guide

Revision 1

On this page

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.ts
  • libs/oshun/shell-desktop/src/types.ts
  • libs/neith/integration-bellona/src/deployment-system/rollout-strategies.ts
  • libs/neith/linux/crates/neith-update-agent/src/rollback.rs
  • apps/bellona/remote-host/src/macos-packaging-plan.ts
  • apps/bellona/remote-host/src/update-manifest.ts
  • docs/domains/bellona/extras/remote-control/macos-packaging-and-notarization-plan.md

External primary references reviewed:

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-host
  • blender-addon
  • unreal-plugin
  • desktop-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-signature for the installer package
  • spctl --assess --type install for the installer package
  • xcrun stapler validate for 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.