104 lines
6.4 KiB
Markdown
104 lines
6.4 KiB
Markdown
# Hydra OS laptop preparation
|
|
|
|
The user authorized autonomous implementation of the agreed scope: preserve all
|
|
existing laptop partitions; install Hydra into an explicitly selected partition;
|
|
obtain updates from the now-public `Emil_Shanaty/Hydra-OS` Gitea repository; verify
|
|
signatures and recover after failed updates; prepare hardware diagnostics; rebuild
|
|
and test an ISO including the generated Fastfetch branding. Technical choices are
|
|
delegated. Actual laptop partitioning/installation and physical hardware checks
|
|
remain operator steps; no physical target is selected or authorized.
|
|
|
|
## Invariants
|
|
|
|
- Never modify the physical host's block devices, firmware, services, NixOS
|
|
configuration, networking, existing containers, or existing VM disks.
|
|
- All installation/recovery execution tests use freshly created private qcow2s.
|
|
- Keep whole-disk installation compatible, but add a distinct existing-partitions
|
|
mode. No automatic partition selection, shrinking, or repartitioning.
|
|
- Preserve foreign EFI files, the removable fallback loader, and BootOrder.
|
|
- VM disks, profiles, HOME, credentials and network configuration are not runtime
|
|
update payloads. Release trust is installed independently of untrusted discovery.
|
|
- Prefer the standard library and already installed OpenSSL; no hosted dependency.
|
|
- Hardware detection is evidence about presence, not proof of working devices.
|
|
- A runtime rollback must never be described as rollback of Gentoo or its kernel.
|
|
|
|
## Existing-partitions installation
|
|
|
|
Keep `--disk` and `--confirm-erase` for fresh whole-disk installations. Add
|
|
`--root-partition`, `--esp-partition`, `--confirm-format`, `--root-fs ext4|btrfs`
|
|
and opt-in `--register-boot-entry`. A request chooses exactly one mode. Existing
|
|
mode formats only the selected root after full identity revalidation, requires an
|
|
unmounted existing FAT ESP, and never runs disk-label/partition/ESP-format commands.
|
|
|
|
Require stable canonical paths, block identities, parent/partition identities and
|
|
bounds; reject mounted/active/protected targets, overlaps, aliases, ambiguous
|
|
metadata and devices with holders. Unrelated mounted sibling partitions must not
|
|
cause false rejection. Btrfs mounts must resolve all backing members conservatively.
|
|
Require enough capacity for the installed payload and boot files before erasure.
|
|
|
|
Write only EFI/HydraOS, refusing an existing collision. Use GRUB --no-nvram without
|
|
--removable, disable os-prober, and leave foreign EFI entries and fallback intact.
|
|
Explicit registration may create a new entry without modifying BootOrder. Default
|
|
output explains manual firmware selection. ESP preflight is read-only and happens
|
|
before root formatting; record and verify unchanged foreign file hashes.
|
|
|
|
Ext4 remains compatible. Optional Btrfs uses @root, @home, @snapshots. The kernel,
|
|
/boot and Portage database remain within @root; guest disks under HOME remain in
|
|
@home. This layout permits a separately verified system recovery path; it alone
|
|
is not a rollback implementation.
|
|
|
|
## Signed runtime updates
|
|
|
|
Use a bounded passive ZIP payload, exact-byte Ed25519-signed JSON manifest and
|
|
detached signature. Manifest records product, scope, format, channel, architecture,
|
|
monotonic sequence, release version, source commit, archive name/size/hash and the
|
|
allowlisted installed paths/modes/hashes. OpenSSL verifies using an installed public
|
|
key. Private release material stays outside Git, the build context and Nix store.
|
|
|
|
Gitea discovery is unauthenticated HTTPS on the fixed project origin; it is not a
|
|
trust authority. Reject cross-origin/downgrade redirects, malformed URLs, duplicate
|
|
JSON/archive entries, traversal/symlinks/special files, excess sizes, tampering and
|
|
unsupported formats. Verify the manifest before trusting the archive. Empty releases
|
|
are a normal result. No fallback to executing unsigned downloaded Python archives.
|
|
|
|
Publication must also work using the already available Git SSH access alone.
|
|
When native releases have no applicable candidate, support the fixed public
|
|
`main/releases/stable` raw path for the same three signed passive artifacts.
|
|
The branch is untrusted transport: the pinned signature, hashes and monotonic
|
|
sequence remain mandatory. Missing artifacts mean no update; invalid signed
|
|
material must produce an error. No API token or extra update server is required.
|
|
|
|
CLI: `hydra update check`, `status`, `apply` and `rollback TRANSACTION`, plus a
|
|
standalone `hydra-update-recover` available when the runtime itself is damaged.
|
|
The trusted engine and recovery bootstrap are outside the runtime update allowlist.
|
|
Prefer a protected installed engine imported without arbitrary sys.path entries.
|
|
For local tests/support permit an explicit trusted local artifact directory and a
|
|
staging-root API; production target checks must still require a Hydra installation.
|
|
|
|
Serialize mutations with a lock. Before the first destination change, validate all
|
|
paths and save original bytes, modes, owners, symlinks and hashes into a durable
|
|
private backup; persist a journal and fsync files/directories. Recover prepared or
|
|
interrupted transactions from independently validated records. Latest-only explicit
|
|
rollback refuses unexpected modifications. Preserve highest accepted sequence when
|
|
rolling back current state; block new changes while recovery is pending. Failure
|
|
must retain the journal and all backups. Include real fresh-process crash tests.
|
|
|
|
## Diagnostics and delivery
|
|
|
|
`hydra doctor` collects a bounded read-only report useful on the live ASUS laptop:
|
|
UEFI/Secure Boot, KVM, CPU/RAM, storage visibility, kernel/driver bindings, graphics,
|
|
input devices, network/audio tools and required services. Redact serials, MACs,
|
|
SSID, IP addresses, usernames and machine IDs by default. Print actionable checks
|
|
without implying physical Wi-Fi/audio/brightness/suspend/144Hz delivery were tested.
|
|
|
|
Rebuild using the isolated existing builder store. Preserve the previous ISO and
|
|
firmware. Run whole-disk acceptance plus a distinct preserve-partitions acceptance:
|
|
seed foreign EFI/fallback/sibling sentinel files, install into only the target,
|
|
compare GPT/BootOrder/sentinels, and boot without ISO. Exercise signed update,
|
|
tamper refusal, rollback and recovery with guest data unchanged. Store reports
|
|
against exact source/ISO hashes. Publish only intended code/artifacts; private
|
|
builder exports, signing keys, VM data and test secrets are never release assets.
|
|
|
|
Whole-base Portage recovery is a separate design/verification unit. Until its own
|
|
bootable test passes, documentation must retain that limitation explicitly.
|