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
- 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".
- 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.
- The owner approves. For each service the owner signs a small admission with an SSH key. No admission, no run.
- 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.
- 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.
- 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.
- 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)
- Every key is a throwaway. Real key custody (offline root on two hardware tokens, FIDO-touched channel signing, an owner key on a device) is not built. No owner record has ever been signed by a physical security key.
- The fetcher is not a separate process; the HTTP source is a test stub with no TLS.
- The "hand-written minimal client versus
tough" decision is a recommendation, not a measurement.toughhas not been run against the attack suite. - Runtime enforcement is not built. Nothing reads the admitted ceiling at run time; "observed versus declared use" is absent.
- Binary services run as the node's own user with no seccomp, namespaces or cgroups, and can rewrite the node's own state file.
- Never run: two or more nodes, placement by Venue, integration with the real gateway,
qr-capgrants or Keycloak. The prototype stands beside them. - Upgrading the node itself (the agent and claim sit outside the distribution by rule) has no channel.
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.