Skip to content

Offer Touch ID as a fingerprint reader once its owner agrees - #12

Merged
maralcbr merged 32 commits into
mainfrom
touchid/fingerprint-readers
Oct 24, 2026
Merged

maralcbr merged 32 commits into
mainfrom
touchid/fingerprint-readers

Conversation

@scottjones

@scottjones scottjones commented Oct 5, 2026 •

Copy link
Copy Markdown
Collaborator

Merge only after its prerequisites below are in. The Omarchy side is omacom/omarchy#14675 (detection) and omacom/omarchy#15512 (enrollment), both merged, and two new Omarchy changes: omacom/omarchy#16403 (removal deletes the reader's own prints) and omacom/omarchy#16360 (the enable-fingerprint and disable-fingerprint dispatch operations, on top of #16403).

Summary

omarchy-mac offers Touch ID as a fingerprint reader, and turns it on only after the Mac's owner agrees. Omarchy's own detection, post-update invitation and fingerprint setup then reach Macs with Touch ID.

Nothing loads the Secure Enclave driver until the owner says yes, and nothing reads the MacBook Neo's device-private sensor key before then either. At boot a status unit records whether this Mac can use Touch ID, without loading anything. Omarchy offers Setup > Security > Fingerprint, and its setup asks the platform first. The consent prompt explains what turning Touch ID on leaves behind, and turns it on only on yes:

 omarchy-mac/
   share/omarchy-platform/
+    fingerprint-readers                   # /run/omarchy-mac/touchid reads "ready" or "available"
   entrypoints/
+    enable-fingerprint                    # the consent prompt; on yes, lib/touchid-enable
+    disable-fingerprint                   # removes the owner's agreement and the Neo's key
   lib/
+    touchid-eligibility                   # can this Mac use it? device tree and files only
+    touchid-status                        # boot: records "available" or "unsupported:<reason>"
+    touchid-enable                        # carves calibration, rebuilds the Neo's key, records agreement, loads apple-sep
+    touchid-root-key                      # rebuilds the Neo's sensor key from its factory records, on yes only
+    touchid-activate                      # "ready" only when enrol and match can work
   share/libalpm/hooks/
+    90-omarchy-mac-touchid.hook           # records the status and activates Touch ID on the update that installs the rule
   vendor/udev/rules.d/
+    94-omarchy-mac-touchid.rules          # starts the activation when /dev/sep-bio appears
   vendor/systemd/system/
+    omarchy-mac-touchid-status.service    # runs touchid-status at boot
+    omarchy-mac-touchid-load.service      # modprobe apple-sep at boot, only with the owner's agreement
+    omarchy-mac-touchid-activate.service  # opens /dev/sep-bio once, only with the agreement and the keybag
+    omarchy-mac-touchid-wait.service      # waits up to 15 s for the node where the driver has a device
+    fprintd.service.d/50-omarchy-mac-touchid.conf  # fprintd starts after the load, wait and activation
   version                                 # 0.2.0
 test/integration/
   runtime                                 # omacom/omarchy 81fd2d23, the merge of #14675
+  fingerprint-readers-test.sh

How consent works

  • Eligible Macs only. available needs:

    • a sensor node;
    • a board the aurora driver has a profile for: M2, M2 Pro and Max, the M3 Air J613 and J615, or the MacBook Neo;
    • /chosen/apfs-preboot-uuid;
    • a way to the calibration;
    • on the Neo, a way to the sensor key: the ESP's asahi/all_firmware.tar.gz and python;
    • an Omarchy that can ask first.

    M1-family Macs are left out: their cold boot needs xart_guard=0, a bigger consent than M2's.

  • Everywhere else, setup goes on. A Mac without a sensor, an M1, or a board without a profile lets Omarchy's setup carry on, so a USB reader enrols on a Mac mini, a Studio or an M1 Mac as it would without Touch ID. A missing status file is worked out again.

  • The prompt covers:

    • Shared state: the enclave's anti-replay state only moves forward, and it is one file in the iBoot System Container that macOS updates too.
    • Risk: this is experimental, non-Apple support, and a bug that writes that state wrongly can cost macOS data. With FileVault on, macOS won't start and the Mac needs a DFU restore. With FileVault off, macOS resets its keychain and Touch ID fingerprints. So back up macOS first.
    • FileVault isn't detected, since it can be turned on after Omarchy is installed.
    • On a Neo only: a line saying the sensor key is read from the factory records the installer left on the boot partition, into a root-only firmware file, and that turning Touch ID off deletes it.
    • A Mac with a key store from an earlier setup is told it will be reused.
  • An existing key store is not consent. That owner never saw this text, so they are asked too. An owner who already agreed is never asked again; a Mac that isn't ready yet is told to restart.

  • Yes carves what is missing into /usr/lib/firmware/updates:

    • the calibration with linux-aurora's extract-mesa-calibration;
    • on the Neo, apple/msrk-j700.bin, rebuilt by touchid-root-key (below).

    It then writes /etc/omarchy-mac/touchid-on and the driver options, loads apple-sep, and succeeds only once the activation records ready. A failure after that takes the record back, unless it was already there, and takes back a key this run rebuilt. Failed writes are reported, never passed off as success.

  • No, an empty answer or a closed terminal leaves Touch ID off and writes nothing.

  • Turning it off, through Omarchy's fingerprint removal, deletes the prints through fprintd first (#16403). It then removes the record, the options and the Neo's key. The driver stops loading from the next boot. The key store stays.

  • At boot, omarchy-mac-touchid-load.service loads apple-sep only while the record exists. It waits for the iBoot System Container's partition link, which the driver opens as it probes, with udevadm wait once its condition holds. It deliberately has no device dependency: systemd waits for a unit's devices before checking its condition, so every boot would wait on the partition. It runs before the greeter and fprintd.

The Neo's sensor key

The Neo's Touch ID needs a device-private sensor root key.

  • How it's rebuilt. touchid-root-key (Python standard library only) rebuilds it only after the owner says yes. It reads this Mac's own factory records from asahi/all_firmware.tar.gz, which asahi-installer writes to the ESP on every install, and assembles the key exactly as omarchy-mac-installer's factory_root_key() does on macOS.
  • How it's checked. It checks the envelope and the seal's chip, then refuses records that aren't all found byte for byte in this Mac's own iBoot System Container. So another Mac's archive, or one swapped on the ESP, gives no key.
  • How it's written. It writes the key 0600, to a temporary file it created, synced and renamed.
  • What's kept. Nothing is kept anywhere else. Turning Touch ID off deletes the key, and the next yes rebuilds it.
  • Factory reset. A reset carries nothing, since the ESP survives it.
  • Older installs. Neos installed before any of this are covered.

This replaces the earlier design, where the installer rebuilt the key on every Neo install (omacom/omarchy-mac-installer#120) and this package kept it in /var/lib/omarchy-mac.

Prerequisites

omacom/linux-aurora#180 changes the consent switch. With #180 the driver autoloads read-only on every Mac (xart_writes=0 provision_keybag=0), and opt-in becomes a modprobe options file. enable-fingerprint already writes that file, /etc/modprobe.d/omarchy-mac-touchid.conf with xart_writes=1 provision_keybag=1, alongside the boot-load record, and disable-fingerprint removes both. How that plays out:

  • Today's kernels: those options are the defaults, so the file changes nothing yet. It sorts after apple-sep.conf, so it wins.
  • The activation runs only on the owner's record. A Mac whose owner hasn't agreed, or turned Touch ID off, keeps the boot's available and is offered Touch ID.
  • Macs agreed before the options file existed get it whatever their status, so one that reads blocked reaches ready after a restart.
  • The driver refuses enrol and verify while xart_writes=0 (linux-aurora cbd3a9b1ad3f).
  • What #180 still needs: fprintd opens /dev/sep-bio when it probes its readers, so fprintd's allowance for it needs the same gate before #180 ships. Once #180 lands, the load unit goes away, and the prompt should say Touch ID stops writing, not that the driver stops loading.

The fingerprint setup installs the published libfprint-git, whose aarch64 build carries the Touch ID driver (omacom/omarchy-pkgs#806), so this package doesn't depend on it.

Evidence

  • MacBook Neo (J700), 2026-10-23, this design end to end at ab5a5b6, with #16403 and #16360's commands installed by hand. Details are in the comment below.

    • The package built on the Neo with 108 tests ok, and the update hook recorded available straight away.
    • On a cold boot without agreement, the load unit was skipped at once, the driver stayed unloaded, and no copy of the key existed.
    • No wrote nothing.
    • Yes rebuilt the key from the ESP archive, byte-identical to the one macOS gives (12,689 bytes, 0600, one copy). Enrol passed.
    • On a cold boot with agreement, the driver was loaded in under 0.1 s and activation read ready. The lock screen and sudo took the finger.
    • Removal deleted the prints through fprintd, then the agreement, the options and the key.
  • MacBook Pro 14" M2 Max (J414c), 2026-10-23, same build, a first-time setup. The calibration was carved on yes. On the agreed cold boot the driver was loaded in under 0.1 s. The lock screen and sudo took the finger, and removal ran in the same order.

  • Earlier runs, in the comments above:

    • This Neo, 2026-10-22, on the earlier staged-key design.
    • The Neo's gate boot, with enrol, verify, sudo, hyprlock and reboot persistence. A 16½-minute lid-closed suspend later unlocked on the first touch.
    • An M2 Max with aurora-touchid. It enrolled through the invitation, and after a 1 h 15 min sleep the lock screen took the finger, as did pkexec and sudo.
    • ludagoo's M1 Air (J313) gate boot, which showed the same path working with xart_guard=0.
  • Tests. The package tests cover:

    • eligibility per board and missing input;
    • the status unit never loading or reading anything;
    • setup going on where Touch ID can't be used;
    • enable carving, recording and taking back on failure, including failed writes;
    • the Neo's key: byte-exact rebuild, root-only, one copy. It is refused for another Mac's container, missing MSRk, seal or trust bytes, two seals, the wrong chip, a truncated or oversized archive, a differing or misnamed trust bundle, a wrong payload, duplicates and symlinks. Decoys and unrelated entries are ignored, and a record across the scan's 8 MiB read boundary is still found. It never writes into a stale temporary file;
    • every prompt variant, with no, empty and closed input;
    • the units' ordering and conditions;
    • the activation's four readiness attributes.

    Every new check was shown to fail against a deliberate break. The integration test runs the runtime against available and ready.

Merge Danger

Door: two-way

The invitation is one-way for each owner: once shown, it doesn't come back. Turning Touch ID on leaves a key store and advances shared Secure Enclave state; the prompt says so before anything is written.

Blast Radius: Macs with Touch ID

🤖 Generated with Claude Code

@maralcbr

maralcbr commented Oct 5, 2026

Copy link
Copy Markdown
Member

@scottjones reviewed at 8f82db6. Keeping this as a draft is right: shipping fingerprint-readers before aarch64 libfprint-git from omacom/omarchy-pkgs#806 is published, and before the aurora-touchid plumbing lives here, would spend the one-time invitation on a setup that can't finish. The udev match keys (ACTION=="add", SUBSYSTEM=="misc", KERNEL=="sep-bio", TAG+="systemd", SYSTEMD_WANTS), no [Install], and the vendor paths are the right shape.

To close before it leaves draft:

  • Install-time activation. The rule only fires on add. On the update that installs it, /dev/sep-bio already exists, so the unit doesn't run and the same-session post-update check won't see ready until a reboot. Start the unit (or udevadm trigger the node) from the install step.
  • Sleep and fprintd. Loading apple-sep, the fprintd drop-in and the resume hook still come from aurora-touchid. Moving them here should replace that package (conflicts/replaces in the recipe), so two openers don't run side by side.
  • The open itself. StandardInput=file: opens read-only, and the ExecCondition process gets the same stdin, so the node is opened and closed twice. Your M2 Max shows ready at boot, so it works today; a line in the unit or README on why read-only is enough (and that the latch survives the last close) would protect it from a kernel change.
  • Tests. fingerprint-readers-test.sh skips unless the runtime literally contains fingerprint-readers, so CI here is green without running it. touchid-activate-test.sh doesn't assert ExecStart=/usr/bin/true.
  • Release hygiene. CONTRIBUTING wants the omarchy-mac/version bump and the manual (which still lists Touch ID as not in the first release) in the PR that changes behaviour.

The apple_sep/*/diag/touchid path is tied to the aurora kernel's naming; worth noting next to the kernel pin so a rename doesn't silently stop the invitation.

@maralcbr

maralcbr commented Oct 5, 2026

Copy link
Copy Markdown
Member

Follow-up after a second review at 8f82db6, on top of my earlier comment. Agreed it stays a draft. Four new points:

  • The oneshot has no start timeout. Type=oneshot disables the start timeout unless TimeoutStartSec= is set. If open("/dev/sep-bio") blocks because the Secure Enclave doesn't answer, the unit stays activating and holds the node, so fprintd can't use it for the rest of the session. Set something short, such as TimeoutStartSec=10s.
  • The hardware evidence doesn't separate this unit from aurora-touchid. The M2 Max run had aurora-touchid installed, which also opens the node, so it doesn't show that this unit's read-only open on its own leaves diag/touchid as ready. Worth one boot with aurora-touchid removed before this leaves draft.
  • What fprintd needs is a DeviceAllow, not a MODE. fprintd runs as root, but its unit only allows USB, SPI, hidraw and /dev/cros_fp. Without a DeviceAllow=/dev/sep-bio rw drop-in, the device cgroup refuses the open. So the fprintd drop-in moving over from aurora-touchid is required, not optional.
  • Tests. fingerprint-readers-test.sh writes only absent and ready. A not-ready (or any other non-ready value) case would catch a runtime that matches by substring and spends the one-time invitation on a sensor that can't enrol. The empty OMARCHY_USB_DEVICES_PATH also never checks that a USB reader is still found once this file exists. touchid-activate-test.sh pins the exact ACTION=="add" line, so the install-time activation fix will need that test changed with it.

@scottjones

Copy link
Copy Markdown
Collaborator Author

Thanks. In 090dac4c…5fdba653:

  • Install-time activation: a pacman hook starts the unit after the transaction that brings the rule; it skips in a chroot or an unbooted root, as systemd's own hooks do.
  • The open: once, from ExecStart, with a note on why read-only is enough. The node takes one opener, so a busy node that already reads ready counts as success (otherwise an update while fprintd holds it showed a hook error); checked on hardware while fprintd held it.
  • Tests: the runtime pin is #694's commit, the skip is gone, and the unit test asserts ExecStart.
  • Release: omarchy-mac 0.2.0 and the manual.
  • Kernel naming: the README notes that the diag/touchid path follows the aurora kernel's names.

Still to do before this leaves draft: taking over aurora-touchid's five pieces (loading apple-sep, extracting the calibration, fprintd's DeviceAllow for misc devices, the wait for /dev/sep-bio, the sleep stop), then moving the pin to the merged commit.

@maralcbr

maralcbr commented Oct 5, 2026

Copy link
Copy Markdown
Member

@scottjones re-reviewed at 5fdba65. Agreed it stays a draft. The install-time hook, the single open from ExecStart, the busy-node success, CI running the integration test, and 0.2.0 with the manual are in. Before it leaves draft, in addition to the five aurora-touchid pieces you listed and the pin move:

  • The hook can hang pacman. The unit still has no TimeoutStartSec= (my earlier point), and the hook's systemctl start waits for the oneshot. If open("/dev/sep-bio") blocks, the post-transaction hook never returns. A short TimeoutStartSec= keeps the same-session behaviour and bounds it; --no-block alone would give that behaviour up.
  • The hook can fail every update. The trigger is the rule file, so it runs on every omarchy-mac upgrade. If the open fails and diag/touchid isn't exactly ready (fprintd mid-enrol, say), the unit fails, the hook exits non-zero, and pacman reports failure after the transaction is committed. Please make the hook always exit 0 (… || true) and leave the result to the unit's journal.
  • A successful open doesn't check ready. If the open returns but the sensor never latches (no calibration, say), the unit and hook succeed and the same-session invitation is missed. Reading diag/touchid after the open as well would make success mean what the detector checks.
  • pacman --root /mnt from a running system isn't a chroot and the host is booted, so the hook starts the host's unit (or fails because the unit only exists under /mnt). Checking that / is the target root would cover it.
  • Still open from my second comment: fprintd's DeviceAllow=/dev/sep-bio rw drop-in, one boot with aurora-touchid removed to show this unit alone reaches ready, and a not-ready value plus a USB reader present in fingerprint-readers-test.sh.
  • The manual describes the finished, tested feature (enrol, then lock screen, sudo, prompts, lid-closed fallback). That's right once the pieces above land, but not yet.

@scottjones

Copy link
Copy Markdown
Collaborator Author

@maralcbr thanks. At 9ff5c0f4:

  • The unit opens /dev/sep-bio once, busy or not, and succeeds only when diag/touchid reads ready within five seconds, with TimeoutStartSec=15s. The kernel activates inside the open (prepare_bio_open → activate_touchid), so this confirms what the detector checks. A unit that never sees ready says so in its journal.
  • The hook ends || true, so it never fails the transaction.
  • pacman --root: libalpm runs every hook through _alpm_run_chroot, which chroot()s into the target root unless it's / (lib/libalpm/util.c:679), so the existing chroot check already stops it. The README and the hook comment now say so.
  • Added the not-ready + USB reader case to fingerprint-readers-test.sh.
  • Still to come before this leaves draft: the fprintd DeviceAllow drop-in and the rest of aurora-touchid's pieces. A boot without aurora-touchid can't show this unit alone yet, since aurora-touchid is what loads apple-sep; I'll run it once module loading moves here.

scottjones added a commit that referenced this pull request Oct 9, 2026
Brings in #18, #19, #20 and #22. The runtime pin conflicted: main pins
omacom/omarchy 4d9bdc49 (#14431), which has no platform-root fingerprint
detection, so this branch now pins omacom/omarchy#14675's head
f317ea50, the fingerprint-readers detector on #14431. Move it to the
merge commit once #14675 lands. omarchy-mac stays at #12's 0.2.0; main
is still at 0.1.0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
scottjones added a commit that referenced this pull request Oct 10, 2026
From Marcelo's review: the invitation rule now says where its names come
from (omarchy-hw-fingerprint, the runtime's detector, reads
fingerprint-readers, the platform file omarchy-mac ships in #12), and
"published" means published to the repositories Macs update from.
systemd-analyze verify --root applies where the container can verify
units, at whatever tree is staged. The runtime pin moves to a commit
that has what a test needs, not the exact commit that added it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
scottjones added a commit that referenced this pull request Oct 10, 2026
Brings in #23. omarchy-mac stays at #12's 0.2.0 over main's 0.1.1, in
the version file and the README. The runtime pin moves to
omacom/omarchy#14675's head 00fcc451, the fingerprint-readers detector
on quattro, since f317ea50 is no longer any PR's head. Quattro renames
the platform from apple-silicon to aarch64-apple, so the platform-name
tests need #24 before this pin passes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
scottjones added a commit that referenced this pull request Oct 10, 2026
Brings in #26's platform names. omarchy-mac stays at #12's 0.2.0, above
main's 0.1.2, in the version file and the README. The runtime pin stays
on omacom/omarchy#14675's head 00fcc451, which sits on main's pinned
quattro e1b0e5e9b; its note now says so. #12's one platform check, the
unit's ExecCondition, already goes through omarchy-hw-apple-silicon.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
scottjones added a commit that referenced this pull request Oct 12, 2026
…ONTRIBUTING.md

AGENTS.md said #12 brought both the platform file and the detector that
reads it. #12 adds fingerprint-readers; omacom/omarchy#14675 teaches the
runtime's omarchy-hw-fingerprint to read it. CONTRIBUTING.md now states
the release rule for one-time prompts beside the cold-boot evidence rule,
so merging the AGENTS.md rule doesn't make policy the contributor guide
leaves out.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
scottjones and others added 13 commits October 18, 2026 16:41
omarchy-hw-fingerprint finds only USB readers, so a Mac's Touch ID sensor,
which the kernel reaches through the Secure Enclave, never got Omarchy's
fingerprint setup. omarchy-mac now names it in
/usr/share/omarchy-platform/fingerprint-readers: the Secure Enclave
driver's diag/touchid reading "ready", which it does only once the sensor
is bound and can enroll and match.

Needs a runtime that reads the file; an older one ignores it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Touch ID activates on the first open of /dev/sep-bio, and until then
diag/touchid reads "unknown", so omarchy-hw-fingerprint found no reader on
a Mac where nothing had opened it: on a Mac without fingerprint setup,
fprintd is not even installed. A udev rule now starts a oneshot unit that
opens it once as soon as the kernel publishes it, and diag/touchid reads
"ready" from boot wherever Touch ID works.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
CI's pinned runtime predates omarchy-hw-fingerprint's platform readers, and
platform_root_copy fails a command that never reads the platform root. The
test now skips until the runtime's detector names fingerprint-readers.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
systemd-analyze verify checks that a unit's commands exist, and on a host
without Omarchy /usr/bin/omarchy-hw-apple-silicon does not, so the test
failed in CI while passing on a Mac with Omarchy installed. It now verifies
the unit with --root at the staged package, where stubs stand in for the
runtime's platform check and true.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The fingerprint setup no longer keeps a platform libfprint: omarchy-pkgs'
libfprint-git builds for aarch64 with the Touch ID driver, and the setup
installs it. The README says so, and that the platform file waits for that
build to be published.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Marcelo's review: the rule fires only on add, and on the install or update
that brings it /dev/sep-bio already exists, so the same session's
post-update check would not see "ready" until a reboot. A pacman hook now
starts the unit after that transaction. The unit opens the node once, from
ExecStart, instead of through StandardInput, which also opened it for the
platform check, and says why a read-only open is enough. The README notes
that the diag/touchid path follows the aurora kernel's naming.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
It skipped unless the pinned runtime named fingerprint-readers, so CI was
green without running it. The pin now names omacom/omarchy#14675's head
(00fcc451: the detector on upstream quattro e1b0e5e9b), and the test no
longer skips. Before this lands the pin moves to #14675's merge commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
CONTRIBUTING puts the version bump and the manual in the change that
brings the behaviour: the keyboard page explains Touch ID, the hardware
table lists it as in progress (tested on the 14" M2 Max), and the status
page no longer leaves it out of the first release.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
/dev/sep-bio takes one opener at a time, so while fprintd holds it the
unit's open fails with EBUSY and the update's pacman hook reported an error
although Touch ID was up. The unit now succeeds when the open works or the
enclave already reads "ready". It opens with true, not ':', because a
failed redirection on a special builtin ends sh before the fallback runs.

The README's condition for shipping the platform file now lists everything
aurora-touchid does today: loading apple-sep, extracting the calibration,
letting fprintd open a misc device and stopping fprintd before sleep.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Grok's review: offline provisioning installs omarchy-mac in a chroot or an
unbooted root, where systemctl start fails and pacman reports a failed hook.
The hook now skips there, as systemd's own pacman hooks do; the first boot's
add event starts the unit instead.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The unit succeeded as soon as /dev/sep-bio opened, even when Touch ID
never latched (no calibration, say), so success didn't mean what the
detector checks. It now opens the node once, busy or not, and succeeds
only if diag/touchid reads "ready" within five seconds.

TimeoutStartSec=15s bounds an open that blocks: the pacman hook waits
for this oneshot, and a hung open would hang the transaction.

A test runs the unit's own command against a fixture node and sysfs:
ready succeeds whether the open worked or the node was busy, and
not-ready fails either way.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The hook runs on every omarchy-mac upgrade, so a unit that failed (say,
fprintd mid-enrollment holding the node and Touch ID not ready) made
pacman report failure after the transaction had committed. The hook now
always exits 0 and leaves the reason to the unit's journal.

pacman --root needs nothing new: libalpm runs hooks chrooted into the
target root, so the chroot check already skips it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A not-ready diag/touchid is no reader, and a USB reader beside it is
still found: the platform file never hides what USB detection finds.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@scottjones
scottjones force-pushed the touchid/fingerprint-readers branch from 9b296cc to 55a5f03 Compare October 18, 2026 21:36
@maralcbr

Copy link
Copy Markdown
Member

@scottjones re-reviewed at 55a5f03. It needs to stay a draft, and one premise in the README has changed.

  • The shipped kernel can now reach ready without aurora-touchid. omarchy-pkgs de782157f (2026-10-18) builds apple_sep in (CONFIG_APPLE_SEP=y), so "nothing loads it on its own" no longer holds. At linux-aurora 5d570a78, provision_keybag and xart_writes both default to 1 (drivers/soc/apple/sep.rs), and run_bringup creates the identity keybag before /dev/sep-bio appears (sbio.rs run_bringup). On the non-nonce_session attach path, complete_bringup runs without the calibration check, and diag/touchid reads ready once activation has started and the sensor is online. So once this merges, its unit could activate Touch ID on a stock Mac and send the one-time invitation, while fprintd still can't open the misc device (no DeviceAllow drop-in yet) and there is no sleep stop. Please update the README's "load apple-sep" item, and gate shipping on one boot without aurora-touchid that shows enroll, verify and suspend working.
  • The boot-time open isn't free on a Mac that isn't set up. Each open runs activate_touchid, which creates /var/lib/aurora-sep-host-state.bin and registers the biometric buffers. On any failure it latches touchid_failed for the rest of the boot ("not safely repeatable"). The unit's default ordering (after basic.target) covers /var/lib on a normal boot, but a later fprintd open can't recover a failure latched this way. Consider ConditionPathExists=/var/lib/aurora-sep-keybag.bin, so the unit only opens the node once a keybag exists.
  • Manual: 06-keyboard.md and 14-status.md describe Touch ID as working and remove it from "not in the first release". That should wait for the boot above.
  • Pin: move test/integration/runtime to #14675's merge commit once it lands.
  • The "Resolve aarch64 package sets" failure also fails on main, so it isn't this PR's.

scottjones and others added 2 commits October 22, 2026 22:03
Once omarchy-mac has moved the installer's copy of a MacBook Neo's Touch ID
sensor key off the ESP, nothing on Linux can bring it back, and a factory
reset boots a root cloned from @factory, which never had it. The key belongs
to the Mac, not its owner, so reset-prepare now copies it into the factory
root as var/lib/omarchy-mac/msrk-j700.bin, 0600 in a 0700 directory: the
copy omarchy-mac kept, or else the one Touch ID was turned on with under
/usr/lib/firmware/updates. The copy goes to a temporary name, is synced and
renamed, and a failure stops the reset before anything is activated. The
next owner is still asked before Touch ID uses it, and since that copy may
not have come straight from the installer, the Neo's prompt now just says a
copy of the sensor key is kept for Linux.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The installer writes the Neo's sensor key to the ESP under a temporary name
and renames it, but on macOS fsync doesn't flush the drive's cache and FAT
has no journal, so a power cut can still leave the key's name on a file that
is short or holds stale clusters. touchid-status moved any non-empty file and
deleted the ESP copy, so Touch ID was offered on a key that can't work, and
the owner would agree only for setup to fail.

It now checks the key's DER envelope first: an outer SEQUENCE whose length
is the file's size, holding the "comb" label and two SEQUENCEs that end
exactly at its end, in a file of at most 16 MiB, reading at most a few
children, so a crafted file can't hold up the boot. A key that fails stays on
the ESP and isn't used, the status says so in its journal, and without
another key the Neo reads unsupported:no-root-key. It is kept rather than
deleted because it is the only copy of a device-private key and the check
is an assumption about its format. The envelope catches a short or
lengthened file and damage that reaches a header; stale bytes inside the
fdrd or secb payload still pass it, and fail only when Touch ID is turned
on. The root's copy is
checked again before it takes the key's name. A temporary
msrk-j700.bin.new that an interrupted write left on the ESP, device-private
like the key, is removed at boot.

The check accepts the 12,689-byte key from a MacBook Neo and rejects it
truncated by one byte, extended by one, or with its first 4 KiB zeroed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scottjones

Copy link
Copy Markdown
Collaborator Author

MacBook Neo (J700) test of the staged sensor key at 7fe0a53, with the installer side from omacom/omarchy-mac-installer#120.

The Neo was a fresh install from a developer build of #120, which staged the key on the ESP. I then installed this PR's package (omarchy-mac 0.2.0-4; makepkg ran test/all on the Neo: 108 ok, 0 not ok) and omacom/omarchy#16360's three commands by hand.

First boot with the package

  • omarchy-mac-touchid-status.service ran at 15.4 s with nothing in its journal.
  • It checked the key's envelope and moved it to /var/lib/omarchy-mac/msrk-j700.bin (0600 root, in a 0700 directory), then removed vendorfw/touchid from the ESP.
  • The status read available.

Setup > Security > Fingerprint

  • Yes copied the key to /usr/lib/firmware/updates/apple/msrk-j700.bin (0600).
  • It wrote /etc/omarchy-mac/touchid-on and /etc/modprobe.d/omarchy-mac-touchid.conf.
  • The status read ready, and enrolment succeeded.
  • The ESP copy, the kept copy and the installed copy have the same SHA-256. That matches the key captured earlier from this Neo.

Cold reboot

  • The status unit finished at 14.2 s (nothing left to move) and the display manager started at 14.8 s.
  • The activation started at 15.6 s and finished at 17.7 s; fprintd started at 17.8 s.
  • The lock screen took the finger, and so did sudo in a terminal.

Removal
On the previous install of this Neo, Omarchy's fingerprint removal with #16360's commands ran fprintd-delete before the PAM and package cleanup. It then removed the agreement record and the driver options, and kept the key store.

🤖 Generated with Claude Code

@scottjones
scottjones marked this pull request as ready for review October 23, 2026 05:30
@scottjones
scottjones requested a review from maralcbr as a code owner October 23, 2026 05:30
@greptile-apps

greptile-apps Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Critical impact] The reviewed changes appear safe to merge once the stated prerequisites are in place.

Summary

Adds Touch ID setup that asks the owner before loading the driver or rebuilding the Neo’s sensor key.

  • Supported Macs can offer Touch ID before the owner turns it on.
  • Touch ID turns on only after the Mac’s owner agrees.
  • Touch ID reports ready only after its driver can enroll and match.

No new actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Boot[Boot] --> Eligibility[Check eligibility without loading the driver]
  Eligibility --> Available[Record available]
  Available --> Prompt[Ask the owner]
  Prompt -->|No| Off[Leave Touch ID off]
  Prompt -->|Yes| Prepare[Prepare missing firmware and record agreement]
  Prepare --> Load[Load driver and activate Touch ID]
  Load -->|Ready| Enroll[Continue fingerprint setup]
  Load -->|Failure| Cleanup[Remove new agreement and rebuilt key]
  Cleanup --> Restart[Record failure and ask for restart]
  Enroll --> Remove[Delete fingerprints]
  Remove --> Disable[Remove agreement, options and Neo key]
Loading

Reviews (7) · Last reviewed commit: "Record a Touch ID that failed to come up..." · Reviewed by Greptile

Comment thread omarchy-mac/lib/touchid-enable Resolved
scottjones added a commit to omacom/omarchy-mac-installer that referenced this pull request Oct 23, 2026
Review follow-up. omarchy_mesa.collect() still took root_key_record= and
would add apple/msrk-j700.bin to the firmware package, with a comment saying
the adapter supplies it; since the adapter stages the key by itself, the
parameter is gone, so the key can't reach the package at all. Its test now
checks that collect() refuses one.

docs/sensor-root-key.md now:
- lists upstream's fallback firmware archive. asahi-installer's
  collect_firmware tars the whole com.apple.factorydata cache, MSRk, seal
  and trust bundle included, into all_firmware.tar.gz, which copy_idata
  puts in the ESP's asahi/ on every install. It is inherited from upstream,
  root-only on Linux through the umask=0077 mount, and
  omacom/omarchy-mac-pkgs#12 doesn't remove it.
- says FAT holds no modes. The staged copy is root-only on Linux through
  the mount and has the mount's permissions on macOS while the installer
  has the ESP mounted; 0600 and 0700 apply in /var/lib/omarchy-mac and the
  installed system.
- says the rename keeps only a write interrupted before it from taking
  the key's name: FAT has no journal and macOS's fsync doesn't flush the
  drive's cache, so a power cut can still leave a damaged file there, which
  Linux's envelope check catches. _stage_neo_sensor_root_key's docstring
  says the same.

Also removes two stray blank lines in the adapter tests.

Re-pinned the engine as v0.9.2-omarchy.20261023.d1f329043a72; two repacks
match and ./test/all passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
scottjones and others added 3 commits October 23, 2026 07:40
…ngs it

Answers Greptile's review of #12:
- The pacman hook starts the status unit before the activation. On the
  update that first installs the package, the boot-time status hasn't
  run and the activation skips without /dev/sep-bio, so nothing offered
  Touch ID until a reboot.
- disable-fingerprint fails when it can't remove the agreement, and
  touchid-enable and enable-fingerprint fail when they can't record it or
  write the driver's options, instead of reporting success.
- The options and the carved calibration are written to .new and renamed,
  so a failed write never leaves a partial file under the real name. A
  truncated options file would load a read-only driver at every boot on a
  kernel with omacom/linux-aurora#180.
- The wait unit follows the boot-time load, so it never looks for the
  device before the driver has one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…artition

Answers the maintainer review of #12:
- enable-fingerprint lets the setup go on wherever Touch ID can't be set
  up, so a USB reader enrols on a Mac mini, a Studio or an M1 Mac. A Mac
  without a sensor writes no status, and a status service can fail, so a
  missing status is worked out again. An owner who agreed already is never
  asked again: the Mac gets any missing driver options and, unless Touch ID
  is ready, is told to restart.
- The load unit waits for the iBoot System Container's link with udevadm
  once its condition holds, instead of depending on the device: systemd
  waits for a unit's devices before checking its condition, so every boot
  waited on the partition, agreed or not, and a machine without one held
  the greeter until the device timed out.
- The activation runs only on the owner's agreement, so on a kernel that
  loads the driver itself (omacom/linux-aurora#180) a Mac whose owner
  hasn't agreed keeps being offered Touch ID.
- The consent text drops a reassurance nobody can check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A MacBook Neo's Touch ID needs its device-private sensor root key. Instead
of an installer copying it before anyone has agreed, and Linux keeping it,
touchid-root-key rebuilds it only after the owner says yes, from this Mac's
factory records in asahi/all_firmware.tar.gz, which asahi-installer writes
to the ESP on every install. It rebuilds the key as the installer's
factory_root_key() does on macOS, checks its envelope, and refuses records
that aren't all found byte for byte in this Mac's own iBoot System
Container, so another Mac's archive, or one swapped on the ESP, gives no
key. It writes the key root-only, to a temporary name it created itself,
synced and renamed.

- Eligibility needs an installed key, or the archive and python.
- The boot status no longer moves a staged key, and nothing is kept in
  /var/lib/omarchy-mac; a yes that then fails takes the rebuilt key back.
- Turning Touch ID off deletes the key; the next yes rebuilds it.
- A factory reset carries no key: the ESP survives it, so the next owner's
  yes rebuilds it. factory-reset.sh is back to its state before 104c496.
- Neos installed before the installer staged anything are covered too.

The README also notes that fprintd opens /dev/sep-bio when it probes, so
a kernel that loads apple_sep on its own (omacom/linux-aurora#180) needs
fprintd's allowance gated on the agreement as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread omarchy-mac/lib/touchid-root-key Resolved
touchid-root-key can fail after its rename, when the directory sync fails,
and then the key was left in place: touchid-enable set its cleanup flag
only once the extractor succeeded. The branch runs only when no key is
installed, so the flag is now set before the extractor runs, and any key
at that name is this run's to take back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scottjones

Copy link
Copy Markdown
Collaborator Author

MacBook Neo (J700) end to end at ab5a5b6, with omacom/omarchy#16403 and #16360's three commands installed by hand, on the same install as the earlier tests.

Before: the old setup's fingerprints were removed through Omarchy, and the old key copies were deleted by hand, including the dev build's kept copy in /var/lib/omarchy-mac. No msrk-j700.bin was left anywhere on the root, and none was on the ESP.

Install: omarchy-mac 0.2.0-5 built on the Neo. makepkg ran test/all: 108 ok, 0 not ok. The update hook ran the status unit, and /run/omarchy-mac/touchid read available before any reboot.

Cold boot, no agreement:

  • The load unit was skipped on its condition at once, and userspace reached the graphical target in 2.8 s.
  • The activation was skipped too. The driver stayed unloaded, and no copy of the key existed.

Setup > Security > Fingerprint:

  • The prompt showed the Neo-only line about reading the sensor key.
  • No: setup stopped with nothing enrolled. There was no agreement and no options, the driver wasn't loaded, no key was written, and the status still read available.
  • Yes:
    • touchid-root-key rebuilt /usr/lib/firmware/updates/apple/msrk-j700.bin from /boot/efi/asahi/all_firmware.tar.gz: 12,689 bytes, 0600, SHA-256 9a772761…. That is byte-identical to the key macOS gives this Neo.
    • It was the only copy on the system.
    • The agreement and the options were written, the status read ready, and enrolment succeeded.

Cold boot, agreed:

Time Event
29.22 s load unit starts; its udevadm wait found the partition link at once
29.30 s load unit finishes
30.76 s activation starts
31.76 s activation finishes, reading ready
32.41 s wait unit starts
32.44 s fprintd starts

The lock screen took the finger, and so did sudo in a terminal.

Removal, through Omarchy's fingerprint removal, in order:

  1. sudo was authenticated.
  2. fprintd-delete scott ran.
  3. The PAM lines and the lock screen's PAM file were removed.
  4. /var/lib/fprint/scott was deleted.
  5. omarchy-lifecycle-dispatch disable-fingerprint ran.
  6. The packages were dropped.

Afterwards the agreement, the options and the key were gone, and the key store stayed. Password unlock on the lock screen worked afterwards.

MacBook Pro 14" M2 Max (J414c), same build, a first-time Touch ID setup (no key store, no calibration, the driver never loaded; m1n1-aurora 1.6.1.aurora20 forwards the preboot UUID):

  • Install: makepkg ran test/all, with 108 ok. The update hook recorded available.

  • Cold boot, no agreement: the load unit was skipped at once and the driver stayed unloaded.

  • No: nothing was written.

  • Yes:

    • The calibration was carved with linux-aurora's extract-mesa-calibration into /usr/lib/firmware/updates/apple/mesa_calibration.bin (64,665 bytes, 0644), with no temporary file left.
    • The key store was created.
    • The status read ready, and enrolment succeeded.
  • Cold boot, agreed:

    Time Event
    21.06 s load unit starts; udevadm wait found the partition link at once
    21.11 s load unit finishes
    24.2 s → 25.1 s activation, reading ready
    28.5 s fprintd starts

    The lock screen and sudo took the finger.

  • Removal: the same order as on the Neo, with fprintd-delete first. The agreement and the options went; the calibration and the key store stayed.

Since then, 696dcf8 answers Greptile's finding: a key the extractor installs before failing is taken back. It changes only that failure path, which the consent tests cover.

🤖 Generated with Claude Code

@scottjones

Copy link
Copy Markdown
Collaborator Author

@maralcbr thanks for the review. Here's what changed for each point, across the four PRs.

omarchy-mac-pkgs#12

  1. USB readers on Macs without usable Touch ID (high). enable-fingerprint now lets setup go on wherever Touch ID can't be set up: no sensor, an M1, a board without a profile. A missing status file is worked out again. An owner who already agreed is never asked again; if Touch ID isn't ready they're told to restart, and setup goes on. It stops setup only on a no, or when turning Touch ID on fails. (d364929)
  2. Every boot waiting on the partition (medium). The load unit no longer depends on the device. It waits for the link with udevadm wait --timeout=20 inside the service, which runs only once ConditionPathExists=/etc/omarchy-mac/touchid-on holds. A machine without the partition, or without an agreement, never waits, and there's no migration. On the Neo the agreed boot loads the driver in under 0.1 s, and an unagreed boot skips the unit at once. (d364929)
  3. Prompt wording. "We haven't seen this…" is gone. (d364929)
  4. Activation without the record. The activation unit now requires /etc/omarchy-mac/touchid-on. (d364929)
  5. Wait unit After=: done in 3a73ebb.
  6. The sensor key: extraction before consent, keeping it, and the factory reset. We moved extraction to Linux, at the moment the owner says yes (ab5a5b6).
    • asahi-installer already leaves this Mac's factory records on the ESP in asahi/all_firmware.tar.gz on every install. touchid-root-key rebuilds the key from them exactly as the installer's factory_root_key() did, then refuses records that aren't all found byte for byte in this Mac's own iBoot System Container.
    • No copy is kept: turning Touch ID off deletes the key, and a failed yes takes it back.
    • A factory reset carries nothing, because the ESP survives and the next yes rebuilds it. factory-reset.sh is back to its state before the carry, so it can no longer refuse over the key.
    • Neos installed before any of this are covered too.
  7. The key check only covering the outer envelope. The staged-key code is gone. The extractor checks the whole comb { fdrd: IMG4 { IM4P(MSRk), [0] IM4M }, secb } structure and binds every record to this Mac's iSC.

Two things your reviews surfaced for #180, noted in the description:

  • fprintd opens /dev/sep-bio when it probes, so its allowance needs the agreement gate before #180 ships;
  • with both a USB reader and a not-ready Touch ID, fprintd-enroll picks the default device, so setup choosing one with -d would be more robust.

omarchy#16360: split as asked. The cross-platform parts are now #16403: removal asking for sudo up front and running fprintd-delete first, and the re-wrapped enrolment text. #16360 carries only the hooks. Setup no longer stops when the platform can't be detected; it warns and goes on as a platform without the hook. So #16360 changes nothing off a Mac, and the dispatcher docs name that exception to failing closed.

omarchy-mac-installer#120: closing it. With extraction on Linux, nothing needs the installer to rebuild or stage the key, so the policy question goes away. #121 is resolved by its option 3: the archive is documented and used.

omarchy-pkgs#1485: agreed. Master's m1n1-aurora already forwards the preboot UUID, and #12's description now says so.

Tested end to end at ab5a5b6, on the Neo and as a first-time setup on an M2 Max (J414c); details are on #12:

  • an unagreed boot;
  • no;
  • yes, with the key rebuilt byte-identical to macOS's;
  • an agreed cold boot, where the lock screen and sudo took the finger;
  • removal.

🤖 Generated with Claude Code

@greptile-apps

greptile-apps Bot commented Oct 23, 2026

Copy link
Copy Markdown

Want your agent to iterate on Greptile's feedback? Try greploops.

The hook records Touch ID's status and starts the activation, but without
the owner's agreement the activation is skipped, so on most Macs it only
checks. "Activating Touch ID..." on every install or update suggested
otherwise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On an M3 Air the driver loaded but the enclave hung and /dev/sep-bio never
appeared, so the activation never ran. The status still read "available",
offering Touch ID again against a driver stuck until a restart, and the
error pointed at the activation's journal, which said only "skipped".

- touchid-enable records "failed" when the driver loaded but the node or
  keybag never appeared, or the activation recorded nothing, and then names
  what's missing and points at journalctl -k. A reason the activation
  recorded stands.
- touchid-status keeps that reason (failed, not-ready, unproven, blocked)
  for the rest of the boot once touchid-enable has loaded the driver, so an
  update's re-run doesn't bring the offer back. The next boot works it out
  again.
- Setup's refusal for those reasons says to restart and try again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@maralcbr maralcbr left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 643e028. Every point from my earlier review is addressed:

  • USB readers enrol where Touch ID can't be used: enable-fingerprint exits 0 for none/unsupported:*, and works out eligibility again when the status file is missing.
  • No partition wait without consent: the load unit waits with udevadm wait inside the service, after ExecCondition, instead of a device dependency.
  • Activation needs the owner's agreement: ConditionPathExists=/etc/omarchy-mac/touchid-on.
  • Wait unit ordered after the load: After=omarchy-mac-touchid-load.service.
  • The prompt drops the unverifiable reassurance.
  • The Neo's sensor key exists only after a yes: touchid-root-key rebuilds it from asahi/all_firmware.tar.gz in memory, checks each record against this Mac's iBoot System Container, and writes it root-only, renaming it only once it is whole. disable-fingerprint deletes it, and the factory-reset carry is gone.

Accepted limitations:

  • Saying no on a Mac that can use Touch ID still stops setup, so a USB reader there can't enrol without saying yes.
  • disable-fingerprint is machine-wide, as removal already is for PAM and the packages.

Follow-ups (non-blocking):

  1. Put one flock around touchid-enable and disable-fingerprint. Two setup runs at once can race on msrk-j700.bin.new, and installed checks only that the key exists, so a damaged key would stay. A shared lock fixes the race, and checking an existing key's envelope would let a bad one be replaced.
  2. Bound touchid-root-key's archive reads by member count and total bytes, not only per record.
  3. Narrow the docstring's "an archive from another Mac, or one swapped on the ESP, is refused". The check proves the records are present in the iBoot System Container, not that they are authentic.
  4. A way to enrol a USB reader after declining Touch ID.

Integration: Touch ID on the Neo now depends on asahi/all_firmware.tar.gz staying on the ESP. omacom/omarchy-mac-installer#121 should close as "keep the archive", not be fixed by removing it.

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.

4 participants