---
id: "CC-TX-2026-10-28-006"
title: "Explicit Device-Only Touch ID Enrollment and Vault Unlock"
date: "2026-10-28"
status: "Active Canon"
from: "Cody Valle"
authorized_by: "Brandon Hatfield, LPC"
---

# Explicit Device-Only Touch ID Enrollment and Vault Unlock

Touch ID enrollment and unlock are now implemented in the native development app. After a password unlock, Settings offers Enable Touch ID on this Mac. Explicit enrollment authenticates with the system and stores the existing v1 vault password in the macOS data-protection Keychain. The item uses biometryCurrentSet and WhenUnlockedThisDeviceOnly with synchronization disabled. Keychain access control, rather than a prompt-only boolean, protects retrieval. This preserves the existing vault and backup format; it does not replace the alpha password-derivation implementation or close its clinical-beta gate.

The vault entrance offers Unlock with Touch ID when enrollment is detected. The automatic privacy cover also offers Return with Touch ID and checks the retrieved secret against the retained protected session. Settings can remove the local enrollment. Password unlock and the Open Passwords launcher remain available. Enrollment identifiers distinguish canonical vault locations. Moving a vault requires enrollment again; stale credentials cannot decrypt a replacement vault with a different password. No real vault or real credential was enrolled in this development work.

The implementation rejects duplicate biometric operations and invalidates late results after cancellation, automatic protection or termination. An enrollment completed after its initiating session is invalidated is removed. Keychain calls run on a dedicated actor, outside the main UI actor. Errors leave password recovery available. Changed fingerprints and different signing identities may require enrollment again; no weaker storage or authentication fallback is substituted.

The final full XCTest run passed 143 tests, zero failures. Seven new mock-backed tests cover enrollment gating and disable/password recovery, authentication failure, stale credentials, canceled/protected pending results and duplicate rejection, vault location separation, protected-session return and wrong-secret rejection. These tests do not exercise real Keychain or Secure Enclave enforcement. The packaged native build and ad hoc signature verification passed. Native UI verification unlocked the synthetic vault with its password, displayed the enrollment controls and started the system Touch ID enrollment request. Successful fingerprint enrollment and Keychain read remain unverified pending human participation. This is an explicit open handoff, not a claim of completed hardware authentication.

The source is preserved in private branch beta/clinical-preview-2026-10-28 at commit 060a4c25bcaa0721fcdb160f109bd75dce55edb6; development app build 20261028204408 identifies revision 060a4c2. TOUCH_ID_UNLOCK.md documents architecture, recovery, signing and acceptance checks. This Mac currently has no valid distribution signing identity. Reliable Keychain access across builds requires an authorized stable signing identity and applicable entitlements. Ad hoc builds may be rejected or lose access after rebuilding; password unlock remains available. Native fingerprint enrollment/read, cancel/lockout, changed fingerprints, protected editors, restart/update and migration checks remain release work. Existing clinical-beta security, key/recovery and workflow gates remain open. Passkey registration has not been implemented.

[Verification inventory](../../docs/evidence/2026-10-28-touch-id.json). Publication authorized in the current development conversation.