Skip to content

Journal reversible Touch ID configuration transitions - #76

Draft
mmdisbrow wants to merge 9 commits into
omacom:mainfrom
mmdisbrow:ready/mac-configuration-transition
Draft

mmdisbrow wants to merge 9 commits into
omacom:mainfrom
mmdisbrow:ready/mac-configuration-transition

Conversation

@mmdisbrow

@mmdisbrow mmdisbrow commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Draft design proposal: a one-time, reversible conversion for administrators retiring an earlier experimental Touch ID configuration after a replacement kernel/provider has been installed, booted and qualified.

Concrete use case: an experimental installation can have PAM includes, release-specific loader-unit overrides and module options that need coordinated replacement while retaining password fallback. A separately reviewed, hash-pinned plan supplies the exact old and new configuration. The tool validates it, journals each atomic replacement and retains the inverse for interruption or rollback. A narrower preserve-existing-consent plan can only add the two absent package-owned consent/options files to an already restored, working installation; it cannot change PAM or authorize enrollment.

Who runs it and when: an administrator/developer from an attended root terminal, once per reviewed transition, with a private checkpoint and exact installed-replacement/module hashes. No plan generator or machine-specific plan ships here. Package install, upgrade and ordinary fingerprint setup never invoke it.

Existing entrypoints remain responsible for normal operation:

  • enable-fingerprint/disable-fingerprint provide the runtime's owner-facing authentication setup.
  • touchid-enable manages consent and startup; touchid-status and touchid-activate handle status/readiness.
  • The proposed touchid-recovery helper is a passive readiness report. It does not repair enrollment, keybags or enclave state.

Maintainer decision requested: is this separate migration tool a workflow the project wants to maintain, or should experimental-installation conversion remain a documented/manual procedure? The local experimental-installation need does not establish a need for stock users. Keep this draft while that scope decision is pending.

Dependencies and limits: live apply requires the kernel's actual host_store diagnostic, an open keystore and a present keybag from the same bound device, plus the other readiness checks. The host-store-readiness companion remains queued and general M1 enablement/anti-replay ownership is unresolved. Filesystem transaction tests do not make this tool deployable.

Validation: the current executable source's 21-test migration suite and package/readiness regressions passed in the preceding follow-up review. This revision adds documentation of operator, use case and entrypoint boundaries only; no new live migration or hardware test is claimed.

Merge order: this draft and #72/#69 currently propose omarchy-mac 0.2.4. Rebase and re-bump if another lands first. If #30 lands first, remove the behavior-PR version bump and duplicated README version line.

AI-assisted implementation and preparation with OpenAI Codex.

Additional prerequisite: retain the test and fallback kernels

A configuration checkpoint does not preserve a kernel's runtime modules. Before qualifying a replacement or relying on a retained fallback, establish retention of each release's complete matching module tree and boot artifacts.

With kernel-modules-hook cleanup enabled, an unowned module tree can be removed when another kernel boots. This includes a previously packaged release retained after an upgrade. A GRUB entry, saved image/initramfs or previously successful boot does not establish continued module availability; the cleanup directory .old is not dependable recovery storage.

Review both boot cleanup and package-transaction hooks before switching kernels. Package ownership alone does not verify module completeness. This transition tool does not provide kernel retention; that requires separate packaging/hook review. The proposed local module-retention repair has not been applied or boot-tested.

AI-generated addendum with OpenAI Codex.

AI-assisted preparation with OpenAI Codex. Validation is recorded in the accompanying review packet; no new DCO sign-off is supplied.
… identity files

AI-assisted preparation with OpenAI Codex. Validation is recorded in the accompanying review packet; no new DCO sign-off is supplied.
AI-assisted fix with OpenAI Codex following independent review. No contributor DCO certification is asserted.
@greptile-apps

greptile-apps Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The documentation revision appears safe to merge as a draft proposal, not as approval for live deployment.

Summary

This revision documents who should run the proposed migration and how it differs from normal Touch ID setup.

  • Administrators can apply a reviewed Touch ID configuration plan and roll it back.
  • A passive report tells the migration tool when Touch ID is ready for a test.

No new actionable issues were found. The earlier helper-installation, directory-sync and shared-lock findings are addressed in the current code. Those threads have no supplied comment numbers.

Reviews (4) · Last reviewed commit: "docs: explain the proposed experimental ..." · Reviewed by Greptile

Comment thread tools/migration/touchid-transition.py Resolved
Comment thread tools/migration/touchid-transition.py Resolved
Comment thread tools/migration/touchid-transition.py Resolved
cursoragent and others added 4 commits October 28, 2026 00:33
Creating /etc/omarchy-mac flushed that directory after the file landed in
it, but not /etc, so a power loss after the journal said APPLIED could drop
the directory. Flush each new directory's parent before the transition is
recorded applied, and roll back if that flush fails.

Co-authored-by: mmdisbrow <mmdisbrow@users.noreply.github.com>
The lock file lived in the checkpoint's parent, so two runs with different
checkpoint directories could change the same configuration together. Hold
one lock at run/omarchy-mac/touchid-transition.lock inside the target root
before creating a checkpoint or replacing a file.

Co-authored-by: mmdisbrow <mmdisbrow@users.noreply.github.com>
Live apply executed /usr/lib/omarchy-mac/touchid-recovery, which no package
installed, so it raised FileNotFoundError before the transition started.
omarchy-mac 0.2.4 ships that program: a passive diag report that never
opens the sensor node. Apply checks that it is installed and executable,
and stops with the path named when it is missing, fails, or is not ready.

Co-authored-by: mmdisbrow <mmdisbrow@users.noreply.github.com>
…ions

Read one bound device consistently and fail closed for missing or unhealthy host-store diagnostics. Require an open keystore and present keybag in both migration gates. Cover failed/missing diagnostics and mixed devices; migration and isolated package suites pass.

AI-assisted follow-up with OpenAI Codex.
@scottjones

Copy link
Copy Markdown
Collaborator

Thanks for this. Before I review it in depth I'd like to understand the problem it solves. What concrete situation needs it: which configuration transitions, who runs the tool, and when? How does it fit with the existing enable-fingerprint/disable-fingerprint entrypoints and the touchid-* scripts? It adds about 1,100 lines, including a new standalone tool and a touchid-recovery script, so I'd also like to check the maintainers want a separate tool for this before we go further.

@mmdisbrow
mmdisbrow marked this pull request as draft October 28, 2026 02:25

Copy link
Copy Markdown
Contributor Author

Thanks for asking. This tool is for an attended administrator converting earlier experimental Touch ID installs using reviewed, hash-pinned plans. Normal setup keeps using the existing enable and disable entrypoints, and the recovery helper only reports status. I'm not sure the maintainers want a separate tool for this, so I've moved it to draft. If you'd prefer a different approach, I'm happy to rework it or close this one.

@mmdisbrow

Copy link
Copy Markdown
Contributor Author

Adding the concrete transitions and validation details to my earlier reply: the use case is retiring an earlier experimental Touch ID setup after its replacement kernel/provider has already been installed, booted and qualified. This would coordinate the old PAM includes, release-specific loader overrides and module options through a separately reviewed, hash-pinned plan with an inverse/checkpoint.

It isn't needed by the normal stock setup, has no automatic hook, and ships no machine-specific transition plan or generator. The existing enable/disable and readiness/consent controls remain the owners of those actions. The recovery command reports state; it does not repair enrollment, keybags or enclave state. The host_store readiness companion is also not yet published.

I reran the 21 isolated transition tests successfully. I haven't qualified a live migration or PAM login with this change. I'll keep it draft: would you prefer this separate administrative tool, or a documented manual procedure? I recommend settling that scope before expanding or merging 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.

3 participants