9. Distribution

State

Partial, and parked. benixos/distribution is a pre-beta prototype with throwaway keys only: 397 tests (channel 181, core 125, node 91), two end-to-end flows on Linux and macOS, Apache-2.0. Not audited, never run against a hardware key, no TLS, no separate fetcher process. In November 2026 the plan was to park it, because a compose bundle pinned by image digest replaces it for the first bootstrap.

A distribution is a named bundle of services, for example a small household: media, home automation, a DNS filter. Think of it as an app store with a notary.

A publisher builds and signs a release. It lands on a channel (nightly, beta, stable), which is just a folder of files that any web server or USB stick can serve. Each node pulls the release, checks everything, works out what can run on itself, and starts only what the owner personally approved.

Nothing the publisher says can approve anything for the owner.

Who does what

Who Role Holds
Publisher Writes the distribution, builds artifacts, signs the release Channel signing keys, one set per channel
Owner Decides which services may run; can roll back One SSH key; its public half is pinned on every node
Channel / mirror Serves static files; not trusted at all Nothing
Node Runs the distribution The owner's public key, a pinned root, a memory of what it has seen

The seven steps

  1. Describe. Three small text files: the services (and how each is delivered: container image, binary, UI), the stack (which are required, recommended, optional), and the distribution (which kinds of machine it supports). Every artifact is pinned by hash; never "latest".
  2. Compile to a lock. A resolver produces one lock, the complete self-contained plan. Its fingerprint, the release id, is a hash of its contents.
  3. The owner approves. For each service the owner signs a small admission with an SSH key. No admission, no run.
  4. Publish. The publisher signs the release onto a channel. Different channels have different signing keys, so a key that is online for nightly can never sign stable.
  5. The node verifies. Signatures meet the threshold; metadata is not expired; it is not older than anything already seen; every file matches its hash and length; the lock hashes to the id claimed; the lock is structurally sane. Any failure leaves the machine as it was.
  6. Plan, check, apply. The node measures itself, the planner decides what runs here and why, then admissions are checked against every planned service. Containers start by digest, read-only, no capabilities, no network. Binaries run only if the operator allows.
  7. Update and roll back. A new release goes through the same path; only what changed restarts. Going backwards needs a record signed by the owner, tied to this node and used once.
flowchart TB
  subgraph PUB["Publisher"]
    A1["service + stack + distribution files"] --> A2["pin artifacts by hash"] --> A3["resolve to LOCK<br/>release id = hash"] --> A4["sign onto a channel"]
  end
  subgraph OWN["Owner"]
    O1["sign one ADMISSION per service"]
  end
  M1[("Channel / mirror<br/>untrusted static files")]
  subgraph NODE["Node"]
    N1{"VERIFY"} --> N3["PROBE this machine"] --> N4["PLAN"] --> N5{"ADMIT?"}
    N5 -- yes --> N6["APPLY pinned artifacts"]
    N1 -- fail --> X["REFUSE, change nothing"]
    N5 -- no --> X
  end
  A4 --> M1 --> N1
  O1 --> N5

What an attacker gets

Attack or accident Result
Unsigned, tampered, truncated or oversized file Refused; nothing changes
An old release replayed, or a stale mirror Refused (the node remembers what it has seen)
Expired metadata Installs blocked; what is running keeps running
A publisher key stolen The thief can publish but cannot make anything run: that needs the owner's admission
A lock that hides or doubles a service Refused as malformed
A file on the node edited behind its back Detected, refused
Power cut mid-update Old state intact, retry works

The prototype's layout

One Cargo workspace of three crates, with benix-node depending on benix-channel depending on benix-dist-core:

Path What
core/ (benix-dist-core) Lock canonicalisation and release id, validation, the plan, owner-signed admissions, an SSHSIG verifier (ed25519, ECDSA P-256 and their FIDO security-key forms)
channel/minimal/ (benix-channel) The TUF-shaped signed channel (root, timestamp, channel roles), the update client, owner records (switch, rollback, reanchor, rekey)
node-lite/ (benix-node) The node: verify, plan, admit, apply, update, roll back
wiring-authority/ A Python reference resolver the Rust tests compare against
spike-mini/ A two-service example (mini-realm, a heartbeat binary; mini-web, traefik/whoami pinned by digest)

Known gaps (the ones that matter most)

Where it fits

Distribution answers "how does a node learn that this set of bytes is what the publisher meant, and may it run?" Venue answers "where may work run?" The node agent answers "whether?". The three are meant to compose: Venue places, the agent checks grants and policy, and a distribution supplies the pinned artifacts. Only the first two meet in code today (chapter 6), and then without grants.

Next

10. Data and identity