Skip to content

Apple factory reset through lifecycle dispatch - #552

Merged
maralcbr merged 4 commits into
quattro-upstreamfrom
mac/34-apple-factory-reset
Sep 25, 2026
Merged

maralcbr merged 4 commits into
quattro-upstreamfrom
mac/34-apple-factory-reset

Conversation

@maralcbr

Copy link
Copy Markdown
Member

Ticket 34. omarchy-system-factory-reset no longer sources omarchy-mac-boot's module on Apple Silicon: it reaches the Mac's boot chain only through omarchy-lifecycle-dispatch, and omarchy-mac-boot implements the reset operations as entrypoints around #503's module.

What changed

  • Core caller. Before the reset is confirmed, reset_boot_owner resolves the reset operations. All resolve: the platform owns the factory root's boot chain. None resolve (x86, Snapdragon, generic aarch64): the existing Limine UKI path runs unchanged. Some, or a resolution failure (Apple without the entrypoints): the reset stops, with the dispatcher's error naming the package.
  • Apple order. Check the current passphrase and stage the throwaway in the factory root. Then reset-prepare <factory-root> [<luks-device>], then reset-verify <factory-root>. After verification the throwaway slot is added and the subvolumes switch. Last, reset-commit receives the throwaway on stdin. If anything fails before the switch, reset-rollback runs, then the slot this attempt added is revoked and the clone is deleted, so the previous root still boots with its own boot files and encryption state.
  • omarchy-mac-boot ships reset-prepare, reset-verify, reset-commit and reset-rollback. Prepare backs up the live boot files and stages the unlock (crypttab and rd.luks.key=). It starts the Limine menu over on the ESP that omarchy-mac-esp names (/boot/efi or /boot), refusing an ESP Limine doesn't write to. It rebuilds inside the factory root and reopens encrypt.state last. Every refusal happens before anything changes: kernel drift from /boot, a bad factory root, device or ESP, a stale reset, or a failed backup. Verify is read-only. It checks the kernel against /boot, that the initramfs loads the firmware before the prompt, and that the unlock is on the GRUB defaults and on the loader's command line. On Limine it also checks the menu's entry for the factory root's machine-id and every UKI hash. Commit writes /boot/omarchy/luks-key durably (mode 600) and drops the backup. Rollback restores the boot files and encrypt.state, and puts the old menu back only when its UKIs are back too.
  • Dispatch contract. This adds one operation, reset-commit, required on Apple. Land #503 with the review fixes and the gap-audit merge blockers #527 writes the Boot-partition key only after the switch, so a power loss before the switch never auto-unlocks the previous root. The three defined operations all run before the switch, so a post-switch step was needed to keep that guarantee. The alternative is to write the key in reset-prepare: that reopens a window of under a second, between the slot being added and the switch becoming durable, where a power loss would auto-unlock the old root. docs/lifecycle-dispatch.md records the arguments, the order and the Apple mapping.
  • Merged quattro-upstream after Security: keep enrolled LUKS2 tokens from passing LUKS key checks #549 and Post-update boot verification blocks update completion and the reboot #543 landed. The factory-reset test keeps Security: keep enrolled LUKS2 tokens from passing LUKS key checks #549's token case on the rewritten harness, and the dispatch doc now carries both the reset rows and Post-update boot verification blocks update completion and the reboot #543's update rows.

Testing

  • New packages/omarchy-mac/boot/test/mac-reset-test.sh runs the staged entrypoints on fixtures. It covers the platform re-check, GRUB and Limine Macs, an ESP at /boot, every verify failure, rollback after each failure point, a partial restore, the kernel/ESP/stale refusals, unencrypted resets and a failed key write.
  • test/shell.d/factory-reset-luks-test.sh now runs stage_full_reset through the real dispatcher. On x86, no Mac entrypoint runs. The Apple cases: a finished reset (prepare → verify → slot → switch → commit, and the throwaway never in argv), a failed verification that rolls back to the previous root with no slot added, and a failure after the slot, where the slot is revoked and the boot state restored. It also covers the token passphrase case (Security: keep enrolled LUKS2 tokens from passing LUKS key checks #549) and a real file-backed LUKS2 volume with a keyring token.
  • Mutation checks: moving the slot before verification, skipping rollback, committing before the switch and skipping verify each fail the suite.
  • A scratch run compared the x86 reset on base and branch. Calls, slots, trees and screen are identical, except for the --token-type flag and a hash of the random throwaway.
  • Ran as non-root in the arm64 Arch container: packages/omarchy-mac/boot/test/all (all ok), and ./test/all on base and branch. Branch fails the same files as base (config, hermes-remove, snapper and unowned-system-paths, which need an omarchy-pkgs checkout), plus system-sleep-ownership-migration-test, which is flaky on base too (2 of 5 base runs failed the same assertion).
  • Real x86 VM on omarchy-gpu, using qcow2 overlays of the existing encrypted integ install. The base tree and this branch each ran omarchy-system-factory-reset in the guest, with the same staged result: throwaway slot, UKI keyfile and drop-ins, a rebuilt UKI keyed to the new machine-id. Both rebooted with no passphrase to "Press Return to Start Setup". VMs and overlays were deleted.
  • Not run: the Apple VM reset (needs ticket 28's harness; exact steps are on the ticket) and hardware. No real machine was reset.

Second review: no blockers. Its verified points are fixed: binds that won't unmount are detached before the clone is deleted, the dispatch doc now notes the new firmware-ordering refusal, and a test covers a second reset attempt after a partial rollback. It asks for one Apple run under the dispatcher's real empty environment, which is in the VM steps.

Factory reset reaches the Mac's boot chain only through
omarchy-lifecycle-dispatch: omarchy-mac-boot's reset-prepare stages and
rebuilds the factory root's boot files, reset-verify proves they boot it,
reset-commit writes the Boot partition key after the switch, and
reset-rollback restores the previous boot state on any earlier failure. x86
keeps its Limine UKI path.
…ple-factory-reset

# Conflicts:
#	bin/omarchy-system-factory-reset
#	docs/lifecycle-dispatch.md
#	test/shell.d/factory-reset-luks-test.sh
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