From 0867c3bb606dafbe6e65de97a0deade4f4b54b30 Mon Sep 17 00:00:00 2001 From: harkl <89045610+h4rkl@users.noreply.github.com> Date: Tue, 27 Oct 2026 22:29:57 +1300 Subject: [PATCH 1/2] release: omit builder SSH keys from signed initramfs A development initramfs includes the build host public keys so the maintainer can recover over USB. Those keys would give the builder root access in every distributed image. Add an explicit release build mode that leaves them out, and reject any signed bundle whose packed initramfs still contains SSH credentials. A real tegu release-mode initramfs differed from the development archive only by the removed root SSH directory. The signed bundle guard rejected the development archive and a corrupt archive, and the Linux integration and full repository tests passed. --- bin/omamobile | 25 ++++++++++++++++---- tests/all | 2 +- tests/make-bundle-keys | 53 ++++++++++++++++++++++++++++++++++++++++++ tools/make-bundle | 8 +++++++ 4 files changed, 82 insertions(+), 6 deletions(-) create mode 100755 tests/make-bundle-keys diff --git a/bin/omamobile b/bin/omamobile index b8ea30aeb..d07f6ffc6 100755 --- a/bin/omamobile +++ b/bin/omamobile @@ -22,7 +22,9 @@ Usage: [DEVICE=] omamobile capture [name] Save what the connected phone exposes (Android over adb, or fastboot) into $REFERENCE_DIR/ - initramfs Build the M1 initramfs (Alpine + dropbear + our init) into $KERNEL_OUT + initramfs [--release] + Build the M1 initramfs into $KERNEL_OUT. --release omits + the builder's SSH keys from distributable boot images initramfs-config Write only the device's files for the shared init (storage-guard allowlist, trigger, ...) into , to check what initramfs packs @@ -328,6 +330,13 @@ cmd_initramfs_config() { cmd_initramfs() { local dl="$WORK/downloads/alpine" stage="$KERNEL_OUT/initramfs" ver=3.24.2 + local release=0 + case ${1:-} in + '') ;; + --release) release=1 ;; + *) die "initramfs: expected --release or no argument" ;; + esac + (($# <= 1)) || die "initramfs: expected --release or no argument" load_device # A leading slash is repo-root relative, so devices share initramfs/init. # Anything else is relative to device//. @@ -442,9 +451,15 @@ cmd_initramfs() { || die "reboot-to failed to link" say "No $DEV_PACKAGE bootctl; built freestanding devmem and musl reboot-to" fi - mkdir -p "$stage/root/.ssh" - cat "$HOME"/.ssh/*.pub > "$stage/root/.ssh/authorized_keys" - chmod 700 "$stage/root/.ssh" && chmod 600 "$stage/root/.ssh/authorized_keys" + rm -rf "$stage/root/.ssh" + if ((release)); then + rm -f "$stage/etc/dropbear"/dropbear_*_host_key + say "Release initramfs: no builder SSH keys" + else + mkdir -p "$stage/root/.ssh" + cat "$HOME"/.ssh/*.pub > "$stage/root/.ssh/authorized_keys" + chmod 700 "$stage/root/.ssh" && chmod 600 "$stage/root/.ssh/authorized_keys" + fi (cd "$stage" && find . | cpio -o -H newc --owner=0:0 --quiet) | lz4 -l -9 -q > "$KERNEL_OUT/initramfs.cpio.lz4" ls -lh "$KERNEL_OUT/initramfs.cpio.lz4" @@ -802,7 +817,7 @@ cmd_kernel_shell() { case "${1:-}" in capture) shift; cmd_capture "$@" ;; - initramfs) cmd_initramfs ;; + initramfs) shift; cmd_initramfs "$@" ;; initramfs-config) shift; cmd_initramfs_config "$@" ;; kernel) cmd_kernel ;; modules) cmd_modules ;; diff --git a/tests/all b/tests/all index d06659ec9..f6037ab15 100755 --- a/tests/all +++ b/tests/all @@ -20,7 +20,7 @@ sh -n device/flame/initramfs/init sh -n device/flame/initramfs/build bash -n tools/build-flame-probe echo "ok - scripts parse" -for t in tests/pr-check tests/kernel-pr-check tests/install-phone tests/phone-provision tests/initramfs-grow tests/images-layout tests/device-overlays tests/simplefb-trigger tests/storage-guard tests/usb-product tests/boot-method tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all; do +for t in tests/pr-check tests/kernel-pr-check tests/install-phone tests/phone-provision tests/initramfs-grow tests/images-layout tests/device-overlays tests/simplefb-trigger tests/storage-guard tests/usb-product tests/boot-method tests/make-bundle-keys tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all; do echo "# $t" "$t" done diff --git a/tests/make-bundle-keys b/tests/make-bundle-keys new file mode 100755 index 000000000..b9731f4e0 --- /dev/null +++ b/tests/make-bundle-keys @@ -0,0 +1,53 @@ +#!/bin/bash +# SPDX-License-Identifier: MIT +# A signed bundle must refuse a development initramfs that grants its +# builder SSH access, while an unsigned development bundle may use it. +set -euo pipefail +cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." +for tool in cpio lz4 sha256sum; do + command -v "$tool" >/dev/null || { echo "ok - # skip: no $tool"; exit 0; } +done +t=$(mktemp -d) +trap 'rm -rf "$t"' EXIT +r=$t/repo +mkdir -p "$r/tools" "$r/device/testdev" "$r/packages/omamobile-keyring" \ + "$r/out" "$t/kernel/include/config" "$t/ramdisk/root/.ssh" +cp tools/make-bundle "$r/tools/" +: > "$r/tools/install-phone" +printf 'BOOT_IMAGES="boot"\nNAME="Test device"\n' > "$r/device/testdev/device.conf" +: > "$r/packages/omamobile-keyring/omamobile.gpg" +echo test-release > "$t/kernel/include/config/kernel.release" +printf x > "$r/out/omamobile-rootfs-test-aarch64.img.zst" +sha256sum "$r/out/omamobile-rootfs-test-aarch64.img.zst" > \ + "$r/out/omamobile-rootfs-test-aarch64.img.zst.sha256" +archive=$t/kernel/initramfs.cpio.lz4 +pack() { + (cd "$t/ramdisk" && find . | cpio -o -H newc --quiet) | lz4 -l -9 -q > "$archive" +} +run() { + DEVICE=testdev KERNEL_OUT="$t/kernel" "$r/tools/make-bundle" --version test \ + --rootfs "$r/out/omamobile-rootfs-test-aarch64.img.zst" "$@" 2>&1 +} +expect_refusal() { + local output + output=$(run "${@:2}") && { echo "not ok - accepted $1" >&2; exit 1; } + grep -cF "$1" <<<"$output" >/dev/null || { + echo "not ok - wrong refusal: $output" >&2; exit 1; + } +} + +printf 'developer key\n' > "$t/ramdisk/root/.ssh/authorized_keys" +pack +expect_refusal 'initramfs contains SSH credentials' +echo 'ok - signed bundle refuses the builder SSH key' +expect_refusal 'holds images for' --unsigned +echo 'ok - unsigned development bundle may pass the key guard' + +rm -rf "$t/ramdisk/root/.ssh" +pack +expect_refusal 'holds images for' +echo 'ok - release initramfs passes the key guard' + +printf corrupt > "$archive" +expect_refusal 'not a valid initramfs archive' +echo 'ok - signed bundle refuses a corrupt initramfs' diff --git a/tools/make-bundle b/tools/make-bundle index 9e076b196..2933f1ace 100755 --- a/tools/make-bundle +++ b/tools/make-bundle @@ -48,6 +48,14 @@ if [[ -z $rootfs ]]; then fi [[ -n $rootfs && -f $rootfs && -f $rootfs.sha256 ]] || die "no root image with a .sha256 (tools/build-rootfs)" release=$(cat "$KERNEL_OUT/include/config/kernel.release" 2>/dev/null) || die "no kernel build in $KERNEL_OUT" +if ((unsigned == 0)); then + initramfs=$KERNEL_OUT/initramfs.cpio.lz4 + [[ -f $initramfs ]] || die "no $initramfs: build it with bin/omamobile initramfs --release" + entries=$(lz4 -dc "$initramfs" | cpio -t --quiet 2>/dev/null) || die "$initramfs is not a valid initramfs archive" + if grep -cE '^(\./)?root/\.ssh(/|$)|^(\./)?etc/dropbear/dropbear_.*_host_key$' <<<"$entries" >/dev/null; then + die "initramfs contains SSH credentials: rebuild with bin/omamobile initramfs --release, then bin/omamobile images" + fi +fi name=omamobile-$DEVICE-$version out=out/bundle From 72483868a14241b4fcf525a392daf250e49dadfb Mon Sep 17 00:00:00 2001 From: harkl <89045610+h4rkl@users.noreply.github.com> Date: Sun, 1 Nov 2026 14:26:44 +1300 Subject: [PATCH 2/2] RELEASES: the release initramfs step and its guard Section 11 builds the initramfs with --release before the images, 5.2 says the flag and the make-bundle refusal exist now, and the section 2 row for the builder's keys moves to done. Co-Authored-By: Claude Opus 5.5 --- docs/RELEASES.md | 42 +++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/RELEASES.md b/docs/RELEASES.md index 00bcc507d..00c63cd51 100644 --- a/docs/RELEASES.md +++ b/docs/RELEASES.md @@ -34,7 +34,7 @@ The audit behind this design (2026-10-13). "Step" names the roadmap step that re | `bin/omamobile capture` | the default capture name `cheetah-` | 1 (done) | | `bin/omamobile push`, `flash` | the partition lookup assumes the main LUN is `sda` | 1 (allowlist check and `BOOT_IMAGES` layouts done; the Pixel 6 has no `init_boot` or `vendor_kernel_boot`, [oriole NOTES](../device/oriole/NOTES.md)), 3 | | `initramfs/init` | `probe()` when `BRINGUP_PROBE=1` and the board matches `COMPATIBLE` (watchdog and DPP reads); the main LUN `sda`. The TRIG_CON write is `SIMPLEFB_TRIG_CON`, the storage-guard allowlist `UFS_RW` and the USB product string `USB_PRODUCT`, all packed from the descriptor into that device's initramfs only | 2 (trigger, allowlist and USB name done; the rest still step 2) | -| `bin/omamobile initramfs` | the developer's `~/.ssh/*.pub` baked in as `authorized_keys` (fine for development, never for a release) | 2 | +| `bin/omamobile initramfs` | the developer's `~/.ssh/*.pub` baked in as `authorized_keys` (fine for development, never for a release); `--release` leaves them out, and `tools/make-bundle` refuses to sign an initramfs that has them | 2 (done) | | `tools/extract-vendor-firmware` | `BOARD="google,gs201-cheetah"`, `DEVICE="cheetah"`, the firmware `MAP` | 4 | | `tools/extract-vendor-chroot`, `extract-fingerprint-vendor` | `DEVICE="cheetah"`, cheetah's file lists | 4 | | `tools/aoc-stage` | the AoC firmware path under `vendor/google/cheetah` | bring-up tool, per plan | @@ -67,19 +67,23 @@ Bring-up tools (`*-stage`, `display-hz`, `usbc-deadman`) stay per plan: they pok | `ROOTFS_PACKAGES` | `omamobile-audio omamobile-sensors omamobile-gnss omamobile-fingerprint omamobile-modem` | Optional. The board's own packages that `tools/build-rootfs` installs on top of the shared `rootfs/packages.omamobile`: ones tuned to this phone, which another device's image must not pull in | | `DTB` | `exynos/google/gs201-cheetah.dtb` | Under `arch/arm64/boot/dts` in the kernel build, and under `dtbs/` in the kernel package | | `SOC_IDS` | `b0:0x9855001 a0:0x9855000` | `label:soc_id`. The first is what the DTB is built with; each other entry is a copy with `/soc_id` rewritten. Order is the order in `dtb.img` | -| `SOC_COMPATIBLE` | (zuma: `b0-foplp:0x9865:1:0:0 b1-foplp:0x9865:1:1:0`; zumapro: `a1-ipop:0x9875:0:1:1`) | For a bootloader that matches the base DTB on `/soc_compatible` instead of `/soc_id` (zuma, zumapro). `label:product_id:major:minor:pkg_mode`, one entry per child node: the label, upper-cased with `-` as `_`, is the node name, so each label appears once. The DTB ships once, unchanged; `images` checks that it has a `/soc_compatible` node holding exactly these children. A descriptor names exactly one of `SOC_IDS` and `SOC_COMPATIBLE`, and `tools/install-phone` checks the same | +| `SOC_COMPATIBLE` | (zuma: `b0-foplp:0x9865:1:0:0 b1-foplp:0x9865:1:1:0`; zumapro: `a1-ipop:0x9875:0:1:1`; gs201 IPOP, the Pixel 7a: `b0-ipop:0x9855:1:0:1`) | For a bootloader that matches the base DTB on `/soc_compatible` instead of `/soc_id` (zuma, zumapro, and gs201's IPOP package). `label:product_id:major:minor:pkg_mode`, one entry per child node: the label, upper-cased with `-` as `_`, is the node name, so each label appears once. The DTB ships once, unchanged; `images` checks that it has a `/soc_compatible` node holding exactly these children. A descriptor names exactly one of `SOC_IDS` and `SOC_COMPATIBLE`, and `tools/install-phone` checks the same | | `DTBO_SOURCE` | `cheetah-m1-overlay.dts` | The board dtbo source beside the descriptor (GPL-2.0) | | `DTBO_BOARD_ID`, `DTBO_BOARD_REV` | `0x30306`, `0x10000` | What ABL matches the dtbo entry on; checked against the source | | `VENDOR_CMDLINE` | `console=tty0 earlycon=exynos4210,0x10A00000 …` | `vendor_boot` command line (kernel arguments really go in `/chosen/bootargs`) | | `VENDOR_PAGESIZE` | `0x800` | Page size of `vendor_boot` (and `vendor_kernel_boot`, where the device has one) | | `OS_VERSION`, `OS_PATCH_LEVEL` | `17.0.0`, `2026-07` | The `init_boot` header values (the `boot` header's, on a device without `init_boot`) | -| `AVB_FOOTERS` | (zuma: `boot:0x4000000 init_boot:0x800000`) | Optional. For a bootloader whose `vbmeta` chains these partitions and, even unlocked, refuses one with no AVB footer (zuma). `image:partition_size`, each a `BOOT_IMAGES` entry, once; the size is the slot's partition size in bytes (stock's footer, `avbtool info_image`, or `fastboot getvar partition-size:_b`), a multiple of 4096. `images` adds a hash footer to each, padding it to that size, signed with AOSP's test key (an unlocked bootloader accepts any key); needs `external/avb` under `SRC_DIR` (or `AVBTOOL`, `AVB_KEY`) and `openssl` | -| `AVB_ROLLBACK_INDEX`, `AVB_SECURITY_PATCH` | `1791158400`, `2026-10-05` | Required with `AVB_FOOTERS`, refused without it: stock's rollback index and `com.android.build..security_patch` from its footers. The `os_version` property is `OS_VERSION`'s major | +| `AVB_FOOTERS` | (zuma, the Pixel 7a and the Pixel 7 Pro: `boot:0x4000000 init_boot:0x800000`) | Optional. For a phone whose `vbmeta_b` chains these partitions, as stock's does: libavb takes a chained partition with no AVB footer as invalid metadata, which an unlocked bootloader doesn't let through (zuma; the Pixel 7a; the Pixel 7 Pro, device/cheetah/NOTES.md 2026-10-28). A `vbmeta_b` that lists them as hash descriptors, or has verification disabled, never reads the footers. `image:partition_size`, each a `BOOT_IMAGES` entry, once; the size is the slot's partition size in bytes (stock's footer, `avbtool info_image`, or `fastboot getvar partition-size:_b`), a multiple of 4096. `images` adds a hash footer to each, padding it to that size, signed with AOSP's test key (an unlocked bootloader accepts any key); needs `external/avb` under `SRC_DIR` (or `AVBTOOL`, `AVB_KEY`) and `openssl` | +| `AVB_ROLLBACK_INDEX`, `AVB_SECURITY_PATCH` | `1791158400`, `2026-10-05` | Required with `AVB_FOOTERS`, refused without it: stock's rollback index and `com.android.build..security_patch` from its footers. Never set the index above stock's: an index the bootloader stores locks stock's own images out of slot A. The `os_version` property is `OS_VERSION`'s major | | `BOOT_METHOD` | `android-v4` (default when omitted) | Generic images, flash, push and installer accept only `android-v4`; other methods are refused before phone access. `ram-only` marks a probe with no persistent install support | | `BOOT_IMAGES` | `boot init_boot vendor_boot vendor_kernel_boot dtbo` | The images written to slot B (the `_b` suffix is added by the tools and is not configurable). `boot`, `vendor_boot` and `dtbo` are always there. Without `init_boot`, `boot` carries the empty generic ramdisk and the OS version; without `vendor_kernel_boot`, `vendor_boot` carries the DTB and the initramfs (the Pixel 6: `boot vendor_boot dtbo`) | | `UFS_RW` | `boot_b … dtbo_b userdata` | The storage guard's allowlist, packed into the initramfs as `/etc/omamobile-ufs-rw`. Only slot B's boot images (`boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b`, `dtbo_b`) and `userdata` are accepted, `userdata` and every `BOOT_IMAGES` entry must be on it, and each name only once. The init fails closed: a missing, empty or malformed file, or any other name in it, leaves every partition read-only | | `INITRAMFS_INIT` | `/initramfs/init` | The init script. A leading `/` is relative to the repo root, so devices share one script. Any other value is relative to the descriptor | -| `SIMPLEFB_TRIG_CON` | `0x1c240030 0x3061` | This device's simplefb trigger write, `addr value`, packed into its initramfs next to `COMPATIBLE`. The init writes it only when that string is the board's first compatible. Absent or empty: no display write. Felix: `0x1c241030 0x3061` (cover, DECON1) | +| `INITRAMFS_MODULES` | (unset) | Optional: kernel modules the initramfs carries in `/lib/modules/omamobile/`, listed in load order in `/lib/modules/omamobile/order`, from this kernel build's `lib/modules/$(kernel_release)` (`omamobile modules` first). The shared init loads them before any other step, and only on a board whose first compatible is `COMPATIBLE`. For drivers the boot needs before the Arch root, such as the PMIC rails a `simple-framebuffer` waits for; `images` refuses an initramfs whose modules come from another build | +| `INITRAMFS_I2C_TOOLS` | (unset) | `1`: `i2cget` and `i2cset` (and `libi2c`) from Alpine's i2c-tools in the initramfs, for an init that talks to a chip before any driver runs (raven closes the MAX77759 USB switch). Nothing else from the package | +| `INITRAMFS_FB_WAIT` | (unset) | `1`: the init draws the early splash once `/dev/fb0` exists (waiting up to 3 s in the background) rather than at once, for a phone whose `simple-framebuffer` registers only after `INITRAMFS_MODULES` give it its rails (raven) | +| `USB_SWITCH` | `10d50000.i2c 0x25` | Optional: the MAX77759 TCPC's I2C controller and address. The init closes the chip's USB2 data switch (`USBSW_CTRL` 0x93 to 0x09) before any driver runs and keeps it closed across replugs, only on a board whose first compatible is `COMPATIBLE`, and only that register and value. Needs `INITRAMFS_I2C_TOOLS=1` (raven) | +| `SIMPLEFB_TRIG_CON` | `0x1c240030 0x3061` | This device's simplefb trigger writes, one or more `addr value` pairs on one line, packed into its initramfs next to `COMPATIBLE`. The init writes each pair only when that string is the board's first compatible. Absent or empty: no display write. Felix: `0x1c241030 0x01003061` (cover, DECON1, tear source DDI1) and `0x1c240030 0x00003061` (inner, DECON0) | | `BRINGUP_PROBE` | `1` | Install the boot probe that reads watchdog and DPP registers. The init runs it only when the board matches `COMPATIBLE`. Absent on a phone whose panels are not driven yet | | `PANEL_SIZE` | `1440x3120` | Portrait panel size for the early splash | @@ -161,7 +165,7 @@ The device package, not the kernel package, turns the kernel into bootable slot- The same Alpine-based initramfs, with release differences: -- **No developer keys.** It ships without `authorized_keys`. The hook appends a second, tiny cpio to the ramdisk that holds the phone's own `/root/.ssh/authorized_keys` (the kernel unpacks concatenated cpio archives in order), so SSH into the initramfs keeps working for the phone's owner and nobody else. +- **No developer keys.** It ships without `authorized_keys`: `bin/omamobile initramfs --release` builds it that way, and `tools/make-bundle` refuses to sign a bundle whose initramfs still holds SSH keys. The hook appends a second, tiny cpio to the ramdisk that holds the phone's own `/root/.ssh/authorized_keys` (the kernel unpacks concatenated cpio archives in order), so SSH into the initramfs keeps working for the phone's owner and nobody else. - **No bring-up probes.** `probe()` and `omamobile.debug` stay in development builds only. - **Quirks from the descriptor.** The trigger write is already per device: `bin/omamobile initramfs` packs `SIMPLEFB_TRIG_CON` into `/etc/omamobile-simplefb-trig` and `COMPATIBLE` beside it. The init writes the pair only when the board's first compatible string matches. A device without the trigger key gets no register write. The storage guard's allowlist is packed the same way, from `UFS_RW` into `/etc/omamobile-ufs-rw`, and the init leaves every partition read-only without a valid one. So is the USB product string (`USB_PRODUCT`, else `NAME`). Step 2 still turns the remaining quirk (`MAIN_LUN`) into a generated `/etc/omamobile/device.conf` the shared init reads at boot. That remaining step changes what boots, so it gets its own runbook and a test boot from `bin/omamobile push`; it is not a refactor. - **Reproducible:** fixed mtimes (`SOURCE_DATE_EPOCH`), sorted file list, `cpio --reproducible`. @@ -219,6 +223,8 @@ The kernel is not touched: it still reaches the phone through `bin/omamobile pus **The phone's update UI** is `omamobile-shell`'s `omamobile.update` sheet: a toast when Omarchy has a release (tap to open) and Update > Omarchy in the menu open it; it shows what's new, the battery and the phone patches, asks for the PIN, shows progress with the output under Details, and ends on the result. The run is a systemd user unit, so it survives the shell restart at its end. +**Kernel module trees.** Omarchy enables `kernel-modules-hook`'s `linux-modules-cleanup.service`, which at every boot moves each `/usr/lib/modules/` that isn't running and that no package owns into `.old`. A phone's kernels come from `bin/omamobile push`, so a boot between a push and the reboot into the new kernel took the next kernel's modules away (seen on the Pixel 7 on 2026-10-27). `omamobile-omarchy` 0.1.14 holds that unit off with a drop-in and runs `omamobile-modules-cleanup.timer` ten minutes after boot instead: it keeps the running release, the release `modules-push` last pushed (named in `/usr/lib/modules/.omamobile-next`), every tree pushed during this boot, every tree stamped before 2026 (a reset clock), every pacman-owned tree and the two newest others, and removes the rest (`/usr/lib/omamobile-omarchy/modules-cleanup --dry-run` shows what it would do). A removed tree comes back with the next `push`, which re-sends a tree whose `.omamobile-tarball` marker is missing. It never touches `.old`, which kernel-modules-hook's own tmpfiles rule empties. + ## 6. Release bundles and the installer For a first install, or to recover a phone that won't boot. One bundle per device per release. @@ -228,7 +234,7 @@ For a first install, or to recover a phone that won't boot. One bundle per devic | Piece | Where | Notes | | --- | --- | --- | | aarch64 packages without a phone | `tools/build-packages` | makepkg in an Arch Linux ARM container (the official tarball, MD5 and signature checked against the pinned build key, `tools/lib/alarm.sh`) under the laptop's qemu-user; signs with `keys/` into `out/repo/aarch64`. Mesa, Hyprland and libcamera take hours this way, so they're built only when named, once per version | -| The shared root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `patches/omarchy`. Output `out/omamobile-rootfs--aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) | +| The device's root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `patches/omarchy`. Output `out/omamobile-rootfs---aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) | | First boot | `packages/omamobile-firstboot` | reads `/etc/omamobile/firstboot.conf` (data, never sourced), creates the user, SSH keys, ufw with SSH on `usb0`, runs Omarchy's own setup leaves (skipping four that don't fit a phone), SDDM autologin and the lock, Omarchy's and our user setup, then deletes the file | | Growing the root | `initramfs/init` (`grow_root`) | `resize2fs` before mounting, only for a file system labelled `omamobile-root` smaller than its partition; `omamobile.noresize` skips it | | The installer | `tools/install-phone` (the bundle's `install`) | as described below, steps 1, 3-5; the factory-image step (2) is `tools/phone-provision` after the first boot instead | @@ -237,6 +243,8 @@ For a first install, or to recover a phone that won't boot. One bundle per devic Decisions taken in building it: the device packages are **installed** in the image, not only cached (one device so far; a first boot without a package step has one less way to fail; §12 decision 6 stays open for the second device); the image's `[omarchy]` is Omarchy's **stable** channel (from 2026-10-20; before that edge was the only one with aarch64 builds of `omarchy`, `omarchy-settings` and `quickshell`, and edge then moved to 4.5.0rc1, which the phone's patches don't apply to); the image is per device (its `MANIFEST` names the device, and the installer refuses a mismatch). +Root image filenames include the device so two devices can share a version without overwriting each other. Builds use separate temporary directories and refuse a concurrent build of the same device/version in the same output directory. Compression and smoke checks finish before replacing the published files. `--local NAME` still uses `out/NAME/repo` and writes images under `out/NAME/`; use `--rootfs` to select one there. Independent package snapshots also need separate `ALARM_CACHE` directories (§10). Repository-mode installation and bundling select only images whose root `MANIFEST` matches the device, including older filenames. + The design: ``` @@ -247,11 +255,13 @@ omamobile--/ images/boot.img init_boot.img vendor_boot.img vendor_kernel_boot.img dtbo.img MANIFEST kernel release, package versions, both repositories' commits SHA256SUMS SHA256SUMS.sig checksums of everything above, signed -omamobile-rootfs--aarch64.img.zst shared by every device, downloaded once - .sha256 .sig +omamobile-rootfs---aarch64.img.zst + .sha256 .MANIFEST ``` -**The shared root image** is an ext4 Arch Linux ARM root with Omarchy, the `[omamobile]` repository configured and its keyring, `linux-omamobile`, `omamobile-shell` and every device package in the package cache but **none installed**. It is built by `pacstrap` in an aarch64 container. It contains no Google file. Its size is a few GB, flashed sparse; the first boot grows it to the whole `userdata` partition (`resize2fs` in the initramfs, before mounting). +**The device's root image** is an ext4 Arch Linux ARM root with Omarchy, the `[omamobile]` repository configured and its keyring, `omamobile-shell`, the device package installed and the matching kernel modules. It is built by `pacstrap` in an aarch64 container. It contains no Google file. Its size is a few GB, flashed sparse; the first boot grows it to the whole `userdata` partition (`resize2fs` in the initramfs, before mounting). + +The bundle's signed `SHA256SUMS` covers its `MANIFEST`, which names the exact root image and its SHA256 digest. The installer checks the selected image's name and bytes against that signed record before contacting the phone; changing the separate `.sha256` cannot authorize a replacement. Bundles use their own checked boot images; `--images` overrides are for repository mode. `--unsigned` remains available for development bundles, which use the root image's `.sha256` check. **`install`** (`tools/install-phone`), run on the laptop with the phone in fastboot: @@ -313,6 +323,16 @@ CI never holds the signing key and never sees a factory image. The maintainer do - Rotation and revocation go through `omamobile-keyring`'s `omamobile-trusted` and `omamobile-revoked`, as Arch's keyring does. - **Publishing** (`tools/repo-publish`): `pkgs.omamobile.org` has two channels, `development/aarch64` and `stable/aarch64`. `repo-publish development` builds what changed (`build-packages --all`), checks every package's checksum and signature against `omamobile-keyring`'s trusted keys, and uploads packages first, then the index, then the pruning; each channel keeps the current and the previous index's files. `repo-publish stable` promotes development's signed files unchanged, after asking. The maintainer's laptop runs it daily from a clean `origin/main` checkout (`--from-main`, `tools/systemd/omamobile-publish.timer`), and `--remind` opens a "Ready for stable" issue when development has differed from stable for three days. Experimental phones' device packages are published to development only. The server account needs the `deployers` group. - Never commit, paste or upload a key, a passphrase or `keys/`. CI gets no key. +- **Contributors' builds** (review lesson L-7). A port's own packages are signed with a local key that only that contributor's machine trusts, and everything lands under `out//` and `keys//`, never in the maintainer's `keys/` or `out/repo`: + + ```sh + tools/local-key-init panther # once: keys/panther/{gnupg,fingerprint,public.asc} + tools/fetch-published out/panther/published # pkgs.omamobile.org/development, each signature checked + tools/build-packages --local panther --import out/panther/published packages/omamobile-device-panther + KERNEL_OUT=... tools/build-rootfs --local panther # out/panther/omamobile-rootfs-*.img.zst + ``` + + `tools/fetch-published` accepts the index and each package only when a key in `omamobile-keyring`'s `omamobile-trusted`, and not in `omamobile-revoked`, signed it, and each package only when it matches the signed index's SHA-256. `build-packages --local` keeps those packages' own `.sig` files, so only what it builds and the repository index carry the local key. The build image of `build-packages` and `build-rootfs --local` trusts the local key too (`ALARM_LOCAL_KEY`, locally signed in that image only). **The phone does not:** after the first boot, `pacman` refuses that `[omamobile]` index until the owner adds the key by hand (`pacman-key --add public.asc`, then `pacman-key --lsign-key `). No package carries a contributor's key. ## 11. Release checklist @@ -321,7 +341,7 @@ Per release, in order. Stop at any failed step. 1. **Kernel:** every subsystem branch meant for the release merged into `omamobile-int`; it boots on each released device, with `uname -r` and the result in that device's NOTES. 2. **Curate:** move what has passed into `omamobile` (§8); publish `omamobile` and the `omamobile-int` snapshot; tag `omamobile-int-`. 3. **Build** the kernel from the tag in the pinned container, release `LOCALVERSION`; pack `linux-omamobile`. -4. **Images** for every device: `DEVICE= bin/omamobile images`, twice, checksums equal. +4. **Images** for every device: `DEVICE= bin/omamobile initramfs --release`, then `DEVICE= bin/omamobile images`, twice, checksums equal. 5. **Packages:** every changed package has a bumped `version`, its `test/all` passes, `tools/build-packages` builds and signs them and the database on the laptop (`tools/repo-build` on a phone only as an opt-in shortcut). 6. **Test install** on each released device, attended: the bundle's `install` on a phone whose stock slot A and backups are known good; first boot, device package installed, `omarchy update` clean, then a package-hook kernel update and a reboot into it. 7. **Identifiers:** grep the bundle, the root image's file list, `MANIFEST` and the release notes for MAC addresses (`[0-9a-f]{2}(:[0-9a-f]{2}){5}`), serial numbers, SSIDs and account names; confirm no file from a factory image is in any artifact.