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