ReviewOS

also looking at this

stacks/drone

feat: own runtime firmware candidates

#49
Merged chris wants to merge codex/runtime-candidate-ownership into main
24 files +1245 -92
docs/runtime-updates.mdmodified+166-16
Changes to docs/runtime-updates.md
@@ -2,10 +2,10 @@
22
33Issue [#9](https://github.com/stacksjs/drone/issues/9) now has offline signed-image
44staging, independent candidate verification, protected initial trust enrollment
5and a persistent host metadata protocol. These commands prepare and verify host
6state. Integrating that protocol with authenticated image staging, revocation,
7installed images, boot selection and known-good rollback slots remains part of
8the full coordinator. Physical deployment is disabled.
5and a persistent host metadata protocol with protected image preparation. These
6commands prepare and verify host state and actual candidate image bytes. Key
7revocation/repair, installed images, boot selection and known-good rollback slots
8remain part of the full coordinator. Physical deployment is disabled.
99
1010## Explicit trust and policy
1111
@@ -136,8 +136,9 @@ compatible target's verified signed declaration. Refresh verifies metadata and
136136declared compatibility; it does not download or authenticate the actual image
137137bytes. An attempt marked `verified` means this metadata operation completed. It
138138does not mean an image is staged, installed, booted or confirmed healthy. Existing
139`updates:stage` and `updates:inspect` remain separate and still report
140`trustStatePersisted: false`; integrating them with this store is unfinished.
139`updates:stage` and `updates:inspect` remain standalone and still report
140`trustStatePersisted: false`. The protected `updates:prepare` path below shares
141that candidate file format and actual-image readback verification.
141142
142143Timestamp or snapshot authority rotation, authenticated through sequential root
143144metadata, creates a new active epoch and invalidates both working-cache entries.
@@ -176,11 +177,158 @@ actual SIGKILL cuts after input and metadata commits, observe SQLITE_BUSY from a
176177competing process, restart and retain the timestamp before a fresh refresh. These
177178cuts do not cover every write/sync boundary or actual physical power loss.
178179
179The v1 format is bounded to 256 attempts, 10,000 metadata advances and a 128 MiB
180The metadata format is bounded to 256 attempts, 10,000 metadata advances and a 128 MiB
180181state database. Each attempt allows 64 inputs, 32 MiB of metadata and 512 KiB per
181182file. Exhaustion fails closed; history is not automatically deleted or compacted.
182183Capacity migration, the full storage-fault campaign, authenticated repair/key
183revocation, image/slot integration and session-bound health remain in #42.
184revocation, durable slot coordination and session-bound health remain in #42.
185
186## Protected signed-image preparation
187
188Use the pinned store and independently trusted current clock to authenticate an
189actual image into a new candidate directory:
190
191```sh
192./buddy updates:prepare /path/to/store --enrollment /path/to/trust \
193 --enrollment-sha256 "$ENROLLMENT_SHA256" --store-sha256 "$STORE_SHA256" \
194 --repository /path/to/offline-repository --output /path/to/new-candidate \
195 --trusted-system-clock-source operator-managed-utc-clock
196```
197
198The library function is `prepareRuntimeFirmwareUpdate`. Native Buddy and the
199compiled CLI use the same function. One writer lease covers metadata verification,
200release-floor commit, image verification and candidate output. It uses one SDK
201metadata pass with the protected cache and journal. It does not perform a second
202unjournaled refresh through the standalone stager.
203
204The signed release floor is committed before reading the image. A bad hash,
205missing image or later output failure cannot reopen a release downgrade. The SDK
206checks actual payload length and SHA-256 before writing, then checks the actual
207written `image.bin` again. The shared candidate file writer emits the same
208`stage.json` format as standalone staging only after repository files and image
209readback complete. Its file helpers do not grant firmware-selection authority.
210
211The candidate's `trust-root.json` is the currently authenticated protected root,
212which can differ from the immutable enrollment root after rotation. Its metadata
213archive includes protected active roles, including cached roles that this attempt
214did not need to fetch again. Both consistent-snapshot filename modes are supported.
215For independent standalone inspection, obtain the current root hash and release
216floor from independently pinned store readback, never from a candidate receipt.
217The candidate does not need to replay the entire initial root chain: the protected
218store has already authenticated that chain and retains its history.
219
220The result schema is `drone-runtime-prepared-image-v1`, with `store` status,
221`candidate` declaration, `trustStatePersisted: true` and
222`physicalDeploymentAllowed: false`. The nested standalone candidate declaration
223still has `trustStatePersisted: false`: that portable receipt is not the protected
224store or current authorization. A successful preparation authenticates these
225candidate bytes at this operation's trusted time. It does not install, select,
226boot or confirm them, and does not promise future trust/expiry policy will allow
227selection. The owned-candidate operation below adds durable reservation records;
228installed/known-good slots and current-policy revalidation before selection remain
229coordinator work in #42.
230
231Image or candidate-output failure during an attempt leaves accepted metadata and
232release floors intact and marks the attempt for maintenance. `updates:recover` replays metadata only; it never
233reconstructs image success or confirms an existing candidate. Preserve partial
234outputs and use a new output directory for a fresh preparation after recovery.
235A complete candidate marker can exist when a later callback or process failure
236prevents the operation returning. Marker existence alone is not authorization.
237Repository, enrollment and protocol-store directories cannot contain the candidate
238output or be contained by it. Existing output directories are not overwritten.
239
240Host tests kill actual competing-writer-excluded processes at `image-written`
241and `candidate-completed` progress points. The first follows image-file sync;
242the second follows the shared file writer's final marker and directory syncs.
243After restart, metadata recovery retains release floor 9 and returns only a store
244summary; a fresh preparation uses another new directory. These measured process
245cuts do not establish every write/sync boundary, electrical power-loss behavior
246or hardware anti-rollback.
247
248## Owned candidate reservations and retirement
249
250Use `updates:reserve` when the pinned store should own the candidate, rather than
251writing a standalone output directory. Repository and enrollment directories must
252remain separate from the store and cannot contain it or be contained by it.
253
254```sh
255./buddy updates:reserve /path/to/store --enrollment /path/to/trust \
256 --enrollment-sha256 "$ENROLLMENT_SHA256" --store-sha256 "$STORE_SHA256" \
257 --repository /path/to/offline-repository \
258 --trusted-system-clock-source operator-managed-utc-clock
259
260./buddy updates:candidates /path/to/store --enrollment /path/to/trust \
261 --enrollment-sha256 "$ENROLLMENT_SHA256" --store-sha256 "$STORE_SHA256"
262
263./buddy updates:retire /path/to/store --enrollment /path/to/trust \
264 --enrollment-sha256 "$ENROLLMENT_SHA256" --store-sha256 "$STORE_SHA256" \
265 --candidate "$EXACT_ACTIVE_CANDIDATE_ID"
266```
267
268The library functions are `reserveRuntimeFirmwareCandidate`,
269`inspectRuntimeFirmwareCandidates` and `retireRuntimeFirmwareCandidate`. The
270native Buddy commands and copied standalone commands share them. A writer lease
271covers metadata verification, reservation, image output and completion. Only one
272candidate can remain active; another reservation fails before starting a metadata
273attempt. A fresh trusted clock and the existing protected SDK operation verify
274the signed selection, then commit its release floor before image acquisition.
275
276Reservation upgrades an exact format1 `state.sqlite` to format2 in one SQLite
277transaction, adding `candidates` and a partial unique index for one active
278reservation. It retains every metadata/attempt record, clock/release floor and
279store identity. `writer.sqlite` stays format1, and the independently retained
280`store.json` hash is unchanged. New code still reads format1 stores without
281migrating them during inspection. Older binaries fail closed on format2; a
282retained older executable was tested before and after upgrade, including unchanged
283state and writer database hashes after its rejection. Do not downgrade or reset a
284store to make an older binary operate on it. Unknown schemas remain rejected
285before configuration that could rewrite their format.
286
287Each candidate record binds a random ID, exact metadata attempt/generation and
288the generated signed-stage description/hash. The record is committed as
289`reserved` before image IO. Files are exclusively created under
290`store/candidates/<id>` with the same actual-image verification and archive writer
291as protected preparation. Only complete file, image and archive readback permits
292the `prepared` record commit. A receipt cannot introduce an owned record.
293
294`updates:candidates` returns `drone-runtime-candidates-v1`, `stateFormat`, protected
295`store` status, the active `candidate`, and bounded declaration `history`. History
296includes retired identities and paths; retired file integrity is not inspected.
297There are at most 128 retained candidate records. Exhaustion fails closed rather
298than deleting history or images. Active candidate `integrity` is:
299
300| Value | Meaning |
301| --- | --- |
302| `incomplete` | The record is still reserved, even if a stage marker exists |
303| `recorded-bytes-match` | Prepared image, receipt, root and archive match the owned record and its historical metadata bytes |
304| `mismatch` | Available file content or layout differs from the owned candidate |
305| `unavailable` | Files cannot be completely read or their protected file/directory requirements fail |
306
307This status is a local byte check. It does not establish fresh TUF expiration,
308revocation or current-policy authorization. `currentTrustValidated` and
309`physicalDeploymentAllowed` remain false. No installed, booted or healthy result
310is invented from a prepared record or matching files.
311
312After an interrupted or failed operation, preserve the whole store and its
313candidate files. Resolve the pending/maintenance metadata attempt with
314`updates:recover` first. Recovery never promotes `reserved` to `prepared`, even
315when a completed stage marker exists. A process can also stop after the prepared
316record commit but before attempt completion; the record survives, while metadata
317recovery still supplies no current selection authority. Missing/corrupt files
318remain actionable integrity failures. Explicit retirement requires the exact
319active ID and a resolved metadata attempt. It changes the record to `retired`,
320retains all files/history/floors, and allows a new ID with a new directory. It does
321not erase or repair the earlier artifact.
322
323Host qualification kills actual processes after reservation, image write, stage
324marker completion, prepared-record commit and retirement commit. Each cut observes
325an actual competing process rejected with SQLITE_BUSY, then restarts, checks
326unchanged candidate phase/floors and prepares a distinct fresh ID after explicit
327recovery/retirement. This does not cover every SQLite/filesystem write or sync,
328ENOSPC/EDQUOT/EIO, electrical power loss or actual board boot behavior. Installed
329and known-good slot roles, identity-bound runtime health, current-policy selection
330and rollback, authenticated key maintenance and the full fault campaign remain
331required by #42.
184332
185333## Repository and signed image contract
186334
@@ -188,9 +336,11 @@ Use a standard TUF repository with `metadata/` and `targets/` directories,
188336including consistent-snapshot names when enabled. Verification uses the pinned
189337[`tuf-js` 6.0.0 client](https://github.com/theupdateframework/tuf-js) for root
190338rotation, signature thresholds, expiration, inter-role versions/hashes and
191target length/hashes. A private, randomly addressed loopback server supplies
192bounded local files to the client's public HTTP interface. It is stopped after
193verification. No external network fetch or arbitrary URL option is provided.
339target length/hashes. Standalone staging/inspection use a private, randomly
340addressed loopback server supplying bounded local files to the public HTTP
341interface, then stop it. Protected refresh/preparation use the public Fetcher
342interface with bounded local files and the durable input journal. Neither path
343provides an external network fetch or arbitrary URL option.
194344The host additionally verifies that root and delegation key IDs equal SHA-256
195345of their canonical key objects, using the upstream canonical JSON library.
196346This rejects arbitrary key-ID aliases before role verification.
@@ -300,11 +450,11 @@ time. Neither path is a complete anti-rollback coordinator. Trusted clock
300450acquisition and protection against privileged clock/storage rollback remain
301451open. Control-loop freshness still uses its separate monotonic clock.
302452
303Initial enrollment and the bounded persistent metadata protocol are available
304above. Complete authenticated maintenance/key revocation, the full storage-fault
305campaign and integration with signed image staging, then installed/known-good
306slot integrity, explicit
307health confirmation and rollback without lowering security floors. Then add
453Initial enrollment, the bounded persistent metadata protocol, protected
454signed-image preparation and durable candidate ownership are available above.
455Complete authenticated maintenance/key revocation and the full storage-fault
456campaign, then installed/known-good slot integrity, explicit health
457confirmation and rollback without lowering security floors. Then add
308458the board bootloader/install protocol and measured power-loss, full-medium,
309459storage-latency and recovery campaigns. Local privileged filesystem tampering
310460is outside this host module's protection; it is not secure boot or hardware