Skip to content

Serialize Touch ID setup, check the Neo's sensor key, bound its archive - #55

Merged
maralcbr merged 5 commits into
mainfrom
touchid-hardening
Oct 24, 2026
Merged

maralcbr merged 5 commits into
mainfrom
touchid-hardening

Conversation

@maralcbr

@maralcbr maralcbr commented Oct 24, 2026 •

Copy link
Copy Markdown
Member

Summary

Three hardening follow-ups to Touch ID from the review of #12, in omarchy-mac 0.2.1. Nothing changes for a Mac whose setup already works.

 omarchy-mac/
   lib/
~    touchid-enable          # takes the Touch ID lock; checks an existing sensor key is whole
~    touchid-root-key        # --check FILE (3 = not whole); caps entries and retained bytes; narrower docstring
   entrypoints/
~    disable-fingerprint     # takes the same lock
~    enable-fingerprint      # repairs an agreed Mac's driver options under the lock
~  test/touchid-consent-test.sh
~  version                   # 0.2.1
  • One setup or removal at a time. touchid-root-key writes the Neo's key through a shared msrk-j700.bin.new and unlinks a stale copy first, so two setups at once could delete each other's open temporary file, or install the other's unfinished key. touchid-enable and disable-fingerprint now take one flock on /run/omarchy-mac/touchid.lock, waiting up to five minutes for a run in progress, then fail without touching anything. enable-fingerprint repairs an agreed Mac's missing driver options under the same lock, so a removal running at the same time can't be undone. A lock that can't be opened is reported as such, not as a setup still running.
  • A sensor key counts only once it is whole. touchid-enable trusted any apple/msrk-j700.bin that existed. Each copy is now checked with touchid-root-key --check, which reuses the envelope check a rebuilt key already passes:
    • a broken copy in updates is rebuilt, and is removed if the rebuild fails;
    • a check that fails to run (--check exits other than 0 or 3) stops setup and leaves the key alone;
    • a broken copy in the base or vendor directory stops setup and names the file, since a rebuild in updates would not replace it;
    • without Python an existing key can't be checked, so setup stops and says so.
  • The factory archive is bounded. factory_records() capped each record at 16 MiB, but not the number of entries or the total kept in memory. It now refuses an archive past 16384 entries, or whose records total more than 32 MiB. asahi-installer's archive holds the recovery's whole /usr/share/firmware tree, the FUD firmware and the factory cache. On an M4 Pro MacBook Pro (macOS 26.6.2) that tree has 3,564 entries, the factory cache 25, and the MSRk, seal and trust records about 16 KB, so the caps leave about 4× and 2,000× headroom. These numbers come from the host macOS, not a Neo's archive.
  • The docstring says what the container check proves. Each record is found byte for byte somewhere in this Mac's iBoot System Container. That shows the record is present there, not that it is the active or an authentic one.

Evidence

  • omarchy-mac/test/all on Arch Linux ARM (aarch64 container), 2026-10-24: 108 ok, exit 0. The Touch ID suite also passes at each of the four commits.

  • New tests:

    • a held lock makes a setup or a removal touch nothing, and a setup waiting for the lock goes on once it is free;
    • a broken key in updates is rebuilt, root-only;
    • a broken key in vendor stops setup and is left alone;
    • a key that can't be checked is not trusted;
    • an archive at the entry limit still gives the key;
    • one entry more is refused, and so are three 12 MiB trust bundles.
  • More tests:

    • a check that fails to run keeps the key and turns nothing on;
    • a broken updates key that can't be rebuilt is removed;
    • a lock that can't be opened says so;
    • an agreed Mac's options repair waits for the lock.

    The waiting test releases the lock only once the setup is seen blocked in flock, so a setup that never waits can't pass it.

  • Every new test fails against a deliberate break (10 in all):

    • no lock in enable, in disable, or in the options repair;
    • enable never waiting;
    • an existence-only key check;
    • a checker failure taken for a broken key;
    • an unopenable lock reported as busy;
    • no entry cap, or the entry cap off by one;
    • no byte cap.
  • Review: GPT-6 Astra (high) found no correctness blocker. Its four P3s are fixed in 8b76938: a checker failure taken for a broken key, a waiting test that could falsely pass, the misleading lock-open error, and the unlocked options repair. It also asked for real-archive sizing, now above. The manual doesn't describe Touch ID setup, so it has no change.

  • Not run on hardware. No setup path changes for a Mac with no key, or with a whole one.

Needs maintainer opt-in

Two restrictions are deliberate, and the review flagged them as policy rather than plain hardening:

  • Setup stops on a broken key in the base or vendor firmware directory, where it went ahead before.
  • Setup stops on a Neo whose key exists but has no Python to check it. Python is already a runtime dependency.

Both stop a Mac that would have loaded a broken key. If either should warn and go on instead, say so and I'll change it.

Merge Danger

Door: two-way

Setup can now stop where it went ahead before: on a Neo whose installed key is broken outside updates, or whose key exists but Python doesn't. Either Mac would have loaded a broken key.

Blast Radius: Macs with Touch ID; on the key check, MacBook Neo only

The docstring said an archive from another Mac, or one swapped on the ESP,
is refused. The check finds each record byte for byte somewhere in this
Mac's iBoot System Container; that proves the record is present there, not
that it is the active or an authentic one.
Each record was capped at 16 MiB, but nothing bounded how many entries the
archive could hold or how many record bytes were kept in memory across
them. factory_records() now refuses an archive past 16384 entries, or whose
records total more than 32 MiB.

Tests: an archive at the entry limit still gives the key; one entry more,
or three 12 MiB trust bundles, are refused and say why.
Two fingerprint setups at once could race on the Neo's sensor key:
touchid-root-key writes it through the shared msrk-j700.bin.new and unlinks
a stale copy first, so one run could delete the other's open temporary file
and install its unfinished key. touchid-enable and disable-fingerprint now
take one lock, /run/omarchy-mac/touchid.lock, waiting up to five minutes
for a run in progress.

touchid-enable trusted any msrk-j700.bin that existed. It now checks each
copy's envelope with touchid-root-key --check: a broken one in the updates
directory is rebuilt, and one elsewhere, which would shadow or outlive a
rebuild there, stops the setup and names the file. Without Python an
existing key can't be checked, so the setup stops and says so.

Tests: a held lock makes a setup or removal touch nothing and one that
waits goes on; a broken key in updates is rebuilt, one in vendor stops the
setup, and one that can't be checked is not trusted.
@maralcbr
maralcbr requested a review from scottjones as a code owner October 24, 2026 00:32
@greptile-apps

greptile-apps Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge, with one non-blocking error-message issue.

Findings

  1. P2 Lock errors get blamed elsewhere ▶

Summary

The PR serializes Touch ID setup and removal, checks installed Neo sensor keys, and caps archive entries and retained record bytes.

  • Touch ID setup and removal take turns using a shared lock.
  • MacBook Neo setup checks its installed sensor key before trusting it.
  • The factory archive scan stays within entry and memory limits.
  • The package release label now reads 0.2.1.

Reviews (2) · Last reviewed commit: "Tell a broken sensor key from a failed c..." · Reviewed by Greptile

…pair

- touchid-root-key --check exits 3 for a key that is not whole and 1 when
  it could not tell. touchid-enable rebuilds only on 3; any other failure
  stops setup and leaves the key alone, where before it took a checker
  that failed to run for a broken key and could delete a good one.
- A lock that can't be opened is reported as such, in touchid-enable and
  disable-fingerprint, not as another setup still running.
- enable-fingerprint's repair of an agreed Mac's driver options takes the
  Touch ID lock and checks the agreement again under it, so a removal
  running at the same time can't be undone.

Tests: a check that fails to run keeps the key and turns nothing on; a
broken key in updates that can't be rebuilt is removed; an unopenable lock
says so; an agreed Mac's options wait for the lock; and the waiting test
releases the lock only once the setup is seen blocked in flock, so a setup
that never waits can't pass it.
Comment on lines +22 to +25
if ! { mkdir -p -m 0755 "${lock%/*}" && exec {lock_fd}>>"$lock"; } 2>/dev/null || ! flock -w 300 "$lock_fd"; then
echo "Touch ID's driver options could not be written: another Touch ID setup or removal is still running." >&2
exit 1
fi

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Lock errors get blamed elsewhere

If Touch ID is already enabled but the driver options are missing, enable-fingerprint reports that another setup is running even when it could not open the lock. The actual error is hidden, so retrying will not help when the lock path cannot be opened.

Separate the open-failure message from the timeout message, as disable-fingerprint and touchid-enable already do.

Suggested change
if ! { mkdir -p -m 0755 "${lock%/*}" && exec {lock_fd}>>"$lock"; } 2>/dev/null || ! flock -w 300 "$lock_fd"; then
echo "Touch ID's driver options could not be written: another Touch ID setup or removal is still running." >&2
exit 1
fi
if ! { mkdir -p -m 0755 "${lock%/*}" && exec {lock_fd}>>"$lock"; } 2>/dev/null; then
echo "Touch ID's driver options could not be written: its lock, $lock, could not be opened." >&2
exit 1
elif ! flock -w 300 "$lock_fd"; then
echo "Touch ID's driver options could not be written: another Touch ID setup or removal is still running." >&2
exit 1
fi

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed in #61 (merged here before this was addressed), with a test for the unopenable lock.

@maralcbr
maralcbr merged commit f2f65b1 into main Oct 24, 2026
7 checks passed
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