# Bellona Remote Host Update Channel And Rollback Plan

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:

- 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-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`.
