5 Distribution and Secure Updates

Racket

5 Distribution and Secure Updates🔗ℹ

package: rivet

The updater treats HTTPS as transport protection, not as its root of trust. Manifests are independently signed with Ed25519 and bind the application ID, version, channel, rollout, rollback policy, artifact byte size, SHA-256 digest, platform, and architecture.

struct
(struct update-artifact ( platform
architecture
url
sha256
size
installer
arguments))
  platform : symbol?
  architecture : symbol?
  url : string?
  sha256 : string?
  size : exact-nonnegative-integer?
  installer : symbol?
  arguments : (listof string?)

Describes one installer artifact bound into the signed manifest.

struct
(struct update-manifest ( application-id
version
build
channel
published-at
minimum-version
previous-version
rollback-allowed?
rollout
artifacts))
  application-id : string?
  version : string?
  build : exact-positive-integer?
  channel : symbol?
  published-at : string?
  minimum-version : string?
  previous-version : (or/c #f string?)
  rollback-allowed? : boolean?
  rollout : exact-nonnegative-integer?
  artifacts : (listof update-artifact?)

Represents the parsed payload covered by an Ed25519 signature.

struct
(struct updater-config ( application-id
current-version
channel
platform
architecture
public-key
expected-key-id
rollout-bucket
maximum-download-bytes))
  application-id : string?
  current-version : string?
  channel : symbol?
  platform : symbol?
  architecture : symbol?
  public-key : any/c
  expected-key-id : (or/c #f string?)
  rollout-bucket : exact-nonnegative-integer?
  maximum-download-bytes : exact-positive-integer?

Holds local identity, trust, rollout, and resource-limit policy.

struct
(struct update-candidate (manifest artifact))
manifest : update-manifest?
artifact : update-artifact?

Pairs an accepted manifest with its current-platform artifact.

struct
(struct install-plan ( candidate
downloaded-path
backup-path
install
restart
rollback))
  candidate : update-candidate?
  downloaded-path : path-string?
  backup-path : (or/c #f path-string?)
  install : procedure?
  restart : procedure?
  rollback : procedure?

Contains the verified artifact and platform-owned lifecycle callbacks.

5.1 Versions and Channels🔗ℹ

procedure
(version? value) → boolean?
value : any/c

Recognizes SemVer 2.0 version strings.

procedure
(version-compare left right) → (or/c -1 0 1)
left : string?
right : string?

Compares SemVer precedence; build metadata does not affect the result.

procedure
(valid-channel? value) → boolean?
value : any/c

Recognizes 'stable, 'beta, and 'dev.

procedure
(channel-accepts-version? channel version) → boolean?
channel : symbol?
version : string?

Checks whether a version is allowed by a release channel.

5.2 Signed Manifests🔗ℹ

update-artifact values describe one platform artifact using the fields platform, architecture, url, sha256, size, installer, and arguments. update-manifest values contain the signed application and release policy plus a list of artifacts.

procedure
(write-signed-manifest manifest
private-key
key-id
[ out]) → void?
  manifest : update-manifest?
  private-key : any/c
  key-id : string?
  out : output-port? = (current-output-port)

Validates, serializes, and signs a manifest payload with Ed25519.

procedure
(verify-signed-manifest input
public-key
[ #:key-id expected-key-id])
→ update-manifest?
  input : input-port?
  public-key : any/c
  expected-key-id : (or/c #f string?) = #f

Verifies the exact signed payload before exposing the parsed manifest.

5.3 Selecting and Installing an Update🔗ℹ

An updater-config records the application ID, current version, channel, platform, architecture, public key, expected key ID, deterministic rollout bucket, and maximum download size.

procedure
(fetch-update-manifest manifest-url
public-key
[ #:key-id key-id
#:maximum-bytes maximum-bytes])
→ update-manifest?
  manifest-url : string?
  public-key : any/c
  key-id : (or/c #f string?) = #f
  maximum-bytes : exact-positive-integer? = (* 1024 1024)

Downloads a bounded manifest from HTTPS and verifies its Ed25519 signature.

procedure
(select-update config manifest) → (or/c #f update-candidate?)
config : updater-config?
manifest : update-manifest?

Applies identity, channel, version, minimum-version, rollout, platform, and architecture policy.

procedure
(download-update config
candidate
destination) → path?
  config : updater-config?
  candidate : update-candidate?
  destination : path-string?

Downloads to a partial file, enforces the signed size and configured bound, verifies SHA-256, and atomically moves the verified artifact into place.

procedure
(execute-install-plan! plan) → any/c
plan : install-plan?

Runs the native installation and restart callbacks. If installation fails and the signed policy allows rollback, the rollback callback runs before the exception is re-raised.

1	Installation
2	Architecture and Module Boundaries
3	Application Backend
4	System Services
5	Distribution and Secure Updates
6	Command-Line Workflow
7	Further Reading

5.1	Versions and Channels
5.2	Signed Manifests
5.3	Selecting and Installing an Update