Skip to content

Seal the install timing as a classed, signed artifact - #178

Draft
LamplighterPaul wants to merge 2 commits into
omacom:quattrofrom
LamplighterPaul:leaderboard/timing-seal
Draft

LamplighterPaul wants to merge 2 commits into
omacom:quattrofrom
LamplighterPaul:leaderboard/timing-seal

Conversation

@LamplighterPaul

@LamplighterPaul LamplighterPaul commented Sep 12, 2026 •

Copy link
Copy Markdown

Stacked on #177; the change to review is the last commit (2a02b6b). Plan: #134.

Why

A leaderboard needs to know which class a result belongs to and that the file it is shown was not edited after the install. Both have to be decided at the finish line, in the live environment, by the installer that observed the run. Nothing about this contacts a server: sharing a result is a separate, explicit step on the installed system, and comes later in the omarchy repo.

What

  • A run_id (UUIDv4) is minted before the first phase, so a failed run has a name in its log too, and the finish screen shows its first eight characters beside the lap time as the run code: 1:18.188 #8dae647e. A photo of the screen can be matched to the sealed document on the target. It moved here from Show install duration with explicit units and sub-minute milliseconds #177 because that is its only job.
  • The timing document gains the ISO's identity (iso_ref, mirror, sha256 of the offline database), the release installed, the class the installer observed (full_disk or protected, encrypted, virtualised, page cache warmed) and a hardware sketch: vendor, product, board, CPU model, memory, target disk and install medium by model, transport and size. No serials, UUIDs, MACs, hostnames or usernames. It is written to /var/lib/omarchy/leaderboard/timing.json as well as the timing log, same bytes in both.
  • After the last phase an Ed25519 keypair is generated with the openssl CLI, the document on disk is signed, and timing.sig and install.pub land beside it. The private key is fed to openssl on stdin and never written; it is gone at reboot. On a btrfs target the three files are copied into the @factory snapshot too.
  • Every probe and the seal itself are best-effort. A failure leaves the plain timing file and a line in the install log, never a failed install.
  • Anyone can check a result with openssl pkeyutl -verify -pubin -rawin -inkey install.pub -in timing.json -sigfile timing.sig. Sealed means tamper-evident, not true: a document and a keypair can be fabricated on any machine. Anti-cheat is class isolation and review on the server side, not this file.

How tested

  • ./test/all: 78 tests green (11 new in test/unit/test_leaderboard.py): class and identity from a fixture live tree, nothing identifying in the document, signature verifies with openssl and breaks on a one-byte edit, no private key on the target or in the state, seal omitted cleanly when openssl is missing, factory copy on btrfs and no-op otherwise.
  • Installed on 2026-09-14 by bin/omarchy-iso-test --install-only --encrypt (QEMU/KVM, 8 vCPU, 8 GB, encrypted full-disk), then the base image booted and inspected over SSH: timing.sig verifies with the openssl one-liner in the guest and on the host, a one-character edit fails, /var/lib/omarchy/leaderboard/timing.json is byte-identical to the timing log, the @factory copies are identical and the snapshot is back to read-only, and no key or PEM material exists under a leaderboard path on the target. Class recorded as {full_disk, encrypted, kvm, warm}. Same result on top of Speed up installs with compressed qcow2 restores and parallel finalization #145's root-image installer (run 874ca20c).

The class and hardware fields describe how the install was done, so #113 and #145 may need a small follow-up here once they land; the lap-time change in #177 does not.

LamplighterPaul added a commit to LamplighterPaul/omarchy-iso that referenced this pull request Sep 12, 2026
The plan described a keypair held in RAM signing exact bytes, a five-field
class tuple with a seed axis, a hint line on the finish screen and an open
question about handles. The code that landed in omacom#177 and omacom#178 makes the key
with openssl, feeds it on stdin, seals the file on disk, records a four-field
class, shows the lap time and run code on one line, and has no handles in v1.
Say what was built; fold the first four phases into the two open PRs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AVshMQURC5nEusD1ka235s
@LamplighterPaul
LamplighterPaul force-pushed the leaderboard/timing-seal branch 3 times, most recently from 928e244 to 5a64f8d Compare September 14, 2026 12:45
@LamplighterPaul
LamplighterPaul marked this pull request as draft September 14, 2026 13:16
LamplighterPaul and others added 2 commits September 15, 2026 03:17
The finish screen rounded the install to whole seconds from two wall-clock
stamps. Now the orchestrator times the run on a monotonic clock, from before
the first phase to after the last, and records the elapsed nanoseconds and a
stable id per phase as its sectors. The dashboard shows the run as a lap
time, m:ss.mmm.

The lap is the same span the screen has always shown, to more digits. The
sectors add up to slightly less than it; the difference is the orchestrator's
own overhead between phases, and is visible in the file for that reason.

The lap time is m:ss.mmm on both sides of the minute, the one shape a lap
time has anywhere in motorsport, so a 34-second install and a six-minute one
read the same way, and h:mm:ss.mmm from an hour, the endurance form. An
earlier revision hid the thousandths from a minute up;
two shapes for one number turned out to be more confusing than the extra
digits.

The wall-clock fields and the phase names are untouched, so the dashboard and
the acceptance harness keep reading what they read. State files without the
new field still render the old m/s form. The installer's preview mode
supplies the field so the finish screen can be rehearsed without an install.

Tested: unit suite green (67 Python tests plus a shell test for the lap time
on both sides of the minute); installed in QEMU on 2026-09-14 by
bin/omarchy-iso-test (encrypted, 8 vCPU, 8 GB).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UD16UHsTsHhAN6viV6aJR
A run id (UUIDv4) is minted before the first phase, so a failed run has a
name in its log too, and the finish screen shows its first eight characters
beside the lap time as the run code: a photo of the screen can be matched to
the sealed document on the target. It moved here from the lap-time change
because that is its only job.

The timing document now carries what a leaderboard needs to place a result:
the ISO's identity (ref, mirror, hash of the offline database), the release
installed, the class the installer observed (full-disk or protected,
encrypted, virtualised, page cache warmed) and a hardware sketch with nothing
that identifies a person. It is written to /var/lib/omarchy/leaderboard/
timing.json as well as the timing log, same bytes in both.

After the last phase an Ed25519 keypair is generated in the live environment,
the document on disk is signed, and timing.sig and install.pub land beside it.
The private key is fed to openssl on stdin and never written; it is gone at
reboot. On a btrfs target the three files are copied into the @factory
snapshot too. Every probe and the seal itself are best-effort: a failure
leaves the plain timing file, never a failed install.

Sealed means tamper-evident, not true. Nothing here contacts a server.

Tested: unit suite (78 tests) green, including seal verification with openssl,
tamper detection, no private key on the target, and the openssl-missing path.
Installed in QEMU on 2026-09-03: seal verified in the guest and on the host,
tampering fails, @factory copy identical.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UD16UHsTsHhAN6viV6aJR
LamplighterPaul added a commit to LamplighterPaul/omarchy-iso that referenced this pull request Sep 17, 2026
Document the draft timing and signing implementation, including artifact
paths, class fields and factory snapshot copies. Group the installer work
into omacom#177 and omacom#178.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant