From 00a22e996835a9a84e6dbbe191561edce5a8de4e Mon Sep 17 00:00:00 2001 From: Chili Palmer Date: Wed, 12 Aug 2026 20:07:09 +0200 Subject: [PATCH] Document safe simulator biometric workflow --- AGENTS.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3d31459..2ddf796 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,12 +46,34 @@ cargo test --workspace For Apple project changes, also run `xcodegen generate` from `apple/` and build the affected simulator targets. +### Updating the Simulator app + +Treat the booted simulator and its app container as persistent test state. To +update IronStorage, build for that simulator and install the new `.app` over +the existing installation with `xcrun simctl install `. +Keep the same device UDID and bundle identifier. + +Do not uninstall IronStorage, erase or recreate the simulator, reset its +keychain, install app-data packages, or delete its app container during an app +update. Those are destructive reset operations, not update steps, and can +remove preferences, repositories, credentials, and biometric enrollment state. + ### Simulator biometric validation -Before testing biometric unlock, enable Biometric Unlock once in the iPhone -app so its protected passphrase is enrolled. In Simulator, use **Features > -Face ID > Enrolled**, trigger an IronStorage unlock, then choose **Matching -Face**. Verify the app changes from locked to unlocked. Use **Non-matching -Face** to test rejection, and clear **Enrolled** to test unavailable or changed -biometric enrollment. -Always tap the entry's **Unlock** control before **Features > Face ID > Matching Face**; a simulated match does nothing without an active authentication request. +For initial setup only, select **Features > Face ID > Enrolled** before enabling +Biometric Unlock in the iPhone app. The user must then enable Biometric Unlock +and enter the GPG passphrase once so the protected passphrase is enrolled. + +For normal validation, do not toggle **Enrolled** again. Tap the entry's +**Unlock** control first so an authentication request is active, then select +**Features > Face ID > Matching Face** and verify the app changes from locked to +unlocked. A matching face presented before **Unlock** does nothing. Use +**Non-matching Face** to test rejection without changing enrollment. + +Apple's `biometryCurrentSet` access control invalidates a protected Keychain +item when Face ID is re-enrolled. Clearing or toggling **Enrolled** is therefore +a destructive negative test, not part of the normal unlock sequence. Only do it +when the issue explicitly requires changed-enrollment coverage and the user is +available to enter the GPG passphrase again. When deliberately returning to a +manual baseline, disable Biometric Unlock in IronStorage while the protected +record is still valid, then clear **Enrolled**.