From 64b9cda16a3cffb002f600dac59a3ced18a3af87 Mon Sep 17 00:00:00 2001 From: xianbin <244479407+watli01@users.noreply.github.com> Date: Tue, 27 Oct 2026 01:15:26 -0400 Subject: [PATCH] Keep native fingerprint presentation across system sleep system_sleep_changed() discarded the cached native projection on both sleep edges, so the resume warmup repeated the full hardware inventory (its own AKS/ACM authorization, Bridge inventory and Catacomb restore) before it could prepare the verifier. Both take the machine-wide operation lock without blocking, so they could only run in sequence. The sleep edge now only advances the inventory generation, so a read straddling it cannot publish, and keeps a completed native projection. runtime_projection() still rechecks the authority and Catacomb/journal state tokens before reuse, native matching still repeats live SEP inventory reconciliation and attestation, and verifier preparation is still released on sleep. On the MacBookPro16,1 reference machine one lid-close resume reached the lock-screen fingerprint prompt 2.42 s after thaw, versus 4.34-4.52 s for the three preceding resumes on the old code. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 10 ++ docs/FPRINT_INTEGRATION.md | 5 +- ...id-resume-presentation-cache-2026-10-27.md | 57 ++++++++ src/t2-fprintd.py | 6 +- tests/test_t2_fprintd.py | 130 +++++++++++++++++- 5 files changed, 204 insertions(+), 4 deletions(-) create mode 100644 docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e546c6..f0d1333 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +### Changed + +- Keep native fingerprint presentation metadata across system sleep while its + account authority, committed Catacomb, and mutation-journal tokens are + unchanged. Resume warmup then prepares the verifier without first repeating + the hardware inventory. Each match still repeats live SEP inventory + reconciliation, and verifier preparation still ends on sleep. One measured + lid-close resume reached the lock-screen prompt in 2.42 s, versus 4.34–4.52 s + before; see the [evaluation](docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md). + ## 0.1.0 - 2026-09-19 This release brings everyday Touch ID commands into one family, makes desktop diff --git a/docs/FPRINT_INTEGRATION.md b/docs/FPRINT_INTEGRATION.md index d102074..9fdbee7 100644 --- a/docs/FPRINT_INTEGRATION.md +++ b/docs/FPRINT_INTEGRATION.md @@ -31,7 +31,10 @@ The repository implements the verification path: collection. Native presentation metadata may remain cached while protected account authority, committed Catacomb metadata, and mutation-journal metadata are unchanged. Separate administrative mutations invalidate reuse on the next - access; compatibility authority always collects fresh state. + access; compatibility authority always collects fresh state. A system sleep + transition stops an in-progress read from publishing but does not itself + discard completed native metadata, so resume warmup can prepare the verifier + without first repeating the hardware inventory. 2. The same caller may pass its single-use list projection to its next `VerifyStart`. Without that projection, verification collects one. Release, enrollment, and deletion invalidate this presentation state. diff --git a/docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md b/docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md new file mode 100644 index 0000000..0470386 --- /dev/null +++ b/docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md @@ -0,0 +1,57 @@ +# Touch ID readiness after resume + +Keeping native presentation metadata across system sleep moved the lock +screen's fingerprint prompt from **4.34–4.52 s to 2.42 s** after resume on the +MacBookPro16,1 reference machine. The hardware inventory no longer runs on the +resume path; verifier preparation now starts as soon as logind reports resume. +Each match still repeats live SEP inventory reconciliation and attestation. + +These measurements end when the lock screen relays the placement prompt. They +do not measure physical-contact-to-result time or a complete graphical login. + +## What changed + +Before this change, `system_sleep_changed()` discarded the cached native +projection on both sleep edges. The resume warmup therefore repeated the full +inventory collection, which performs its own AKS and ACM authorization, Bridge +inventory, and Catacomb restore, before it could start the verifier. Both +operations take the machine-wide operation lock without blocking and both open +AKS/ACM, so they cannot overlap. + +The sleep edge now advances the inventory generation, so a read that straddles +it cannot publish, but it keeps a completed native projection. The next use +still compares the account-authority token and the committed Catacomb and +mutation-journal state token. Verifier preparation is still released on sleep +and rebuilt after resume; no AKS keybag or ACM context crosses a suspend. + +## Measurement conditions + +Linux `7.2.11-arch1-Watanare-T2-1-t2-amdoff`, Python 3.14.8, deep sleep +initiated by closing the lid. The machine carried local, out-of-tree resume +repairs for unrelated platform devices; they are not part of T2Touch and +suspend/resume remains unqualified as described in the +[sleep policy](../SLEEP_POLICY.md). Times are from the systemd journal, +measured from `user.slice` thaw. Profiling was off. + +| Resume | Code | PAM start | Prompt | Inventory | Verifier preparation | +| --- | --- | ---: | ---: | --- | ---: | +| 1 | before | +0.273 s | +3.897 s | collected, 1,952 ms | 1,764 ms | +| 2 | before | +0.292 s | +3.918 s | collected, 1,948 ms | 1,785 ms | +| 3 | before | +0.262 s | +3.874 s | collected, 1,909 ms | 1,775 ms | +| 4 | before | +0.316 s | +4.522 s | collected, 2,250 ms | 1,960 ms | +| 5 | before | +0.253 s | +4.441 s | collected, 2,152 ms | 2,021 ms | +| 6 | before | +0.255 s | +4.341 s | collected, 2,102 ms | 1,974 ms | +| 7 | after | +0.283 s | +2.422 s | cached, 0.0 ms | 2,076 ms | + +Resume 1 ran on the machine's non-`amdoff` kernel build; resumes 2–3 and 4–6 +ran in two later boots of the candidate's kernel. Resumes 4–6 come from the +boot immediately before the candidate and are its closest baseline; why they +are slower than 2–3 was not investigated. Before the change, verifier preparation +began 1.92–2.30 s after thaw; after it, at +0.044 s. Its internal AKS phases +were unchanged: about 0.27–0.29 s keybag retention, 0.55 s ACM context +authorization, and 0.56–0.58 s identity unlock. This is one candidate resume, +not a latency distribution. + +The candidate's lock-screen match completed with post-match attestation, PAM +reported success, and the session unlocked. No negative control, enrollment, +deletion, or password-fallback path was exercised in this comparison. diff --git a/src/t2-fprintd.py b/src/t2-fprintd.py index 8f00c22..e6c840b 100755 --- a/src/t2-fprintd.py +++ b/src/t2-fprintd.py @@ -1103,7 +1103,11 @@ def system_sleep_changed(self, sleeping: bool) -> None: self.sleep_generation = getattr(self, "sleep_generation", 0) + 1 generation = self.sleep_generation self.system_sleeping = sleeping - self.invalidate_inventory("system_sleep") + # A read straddling this edge must not publish. A completed native + # presentation survives: runtime_projection() rechecks its authority + # and state tokens before reuse, and native matching still repeats + # the live SEP inventory. + self.inventory_generation = getattr(self, "inventory_generation", 0) + 1 if sleeping: previous = getattr(self, "native_worker_sleep_task", None) diff --git a/tests/test_t2_fprintd.py b/tests/test_t2_fprintd.py index 1b60f64..81a0859 100644 --- a/tests/test_t2_fprintd.py +++ b/tests/test_t2_fprintd.py @@ -1659,7 +1659,8 @@ async def test_sleep_quiesces_worker_and_resume_schedules_warmup(self): backend = MODULE.T2Backend.__new__(MODULE.T2Backend) backend.system_sleeping = False backend.inventory_generation = 0 - backend.inventory_projection = object() + projection = object() + backend.inventory_projection = projection backend.inventory_authority_token = object() backend.native_worker_warm_task = None backend.native_worker_sleep_task = None @@ -1670,15 +1671,140 @@ async def test_sleep_quiesces_worker_and_resume_schedules_warmup(self): backend.system_sleep_changed(True) sleep_task = backend.native_worker_sleep_task self.assertTrue(backend.system_sleeping) - self.assertIsNone(backend.inventory_projection) + self.assertEqual(backend.inventory_generation, 1) + self.assertIs(backend.inventory_projection, projection) await sleep_task backend._quiesce_hardware_for_sleep.assert_awaited_once_with(1) backend.system_sleep_changed(False) await asyncio.sleep(0) self.assertFalse(backend.system_sleeping) + self.assertEqual(backend.inventory_generation, 2) backend.warm_runtime.assert_awaited_once_with() + def sleep_cache_backend(self): + backend = MODULE.T2Backend.__new__(MODULE.T2Backend) + backend.system_sleeping = False + backend.sleep_generation = 0 + backend.inventory_generation = 0 + backend.inventory_projection = None + backend.inventory_authority_token = None + backend.inventory_state_token = None + backend.native_worker_warm_task = None + backend.native_worker_sleep_task = None + backend.runtime_warm_task = None + backend.operation_lock = asyncio.Lock() + backend._quiesce_hardware_for_sleep = AsyncMock() + backend._inventory_state_token = mock.Mock(return_value=("state-a",)) + authority = mock.Mock( + origin=MODULE.NATIVE_AUTHORITY, + mapping_set=mock.Mock(generation="mapping-a"), + selected=mock.Mock( + linux_account_generation="account-a", + keybag_sha256="keybag-a", + apple_uid=501, + account_uuid="account-uuid-a", + bag_uuid="bag-uuid-a", + ), + ) + backend.runtime_authority = mock.Mock(return_value=authority) + return backend, authority + + async def test_sleep_cycle_reuses_presentation_only_while_tokens_match(self): + backend, authority = self.sleep_cache_backend() + backend.warm_runtime = AsyncMock() + before = MODULE.t2_fprint_runtime.RuntimeProjection(("finger-1",), 1, True) + after = MODULE.t2_fprint_runtime.RuntimeProjection( + ("finger-1", "finger-2"), 2, True + ) + backend._collect_runtime_projection = AsyncMock(side_effect=(before, after)) + + with mock.patch.object(MODULE.t2_performance, "emit"): + self.assertIs(await backend.runtime_projection(), before) + backend.system_sleep_changed(True) + await backend.native_worker_sleep_task + with self.assertRaisesRegex(RuntimeError, "sleep transition"): + await backend.runtime_projection() + backend.system_sleep_changed(False) + await backend.runtime_warm_task + + self.assertIs(await backend.runtime_projection(), before) + backend._collect_runtime_projection.assert_awaited_once_with(authority) + + # The usual tokens still guard reuse after resume. + backend._inventory_state_token.return_value = ("state-b",) + self.assertIs(await backend.runtime_projection(), after) + self.assertEqual(backend._collect_runtime_projection.await_count, 2) + + async def test_sleep_cycle_refreshes_presentation_after_authority_change(self): + backend, authority = self.sleep_cache_backend() + backend.warm_runtime = AsyncMock() + before = MODULE.t2_fprint_runtime.RuntimeProjection(("finger-1",), 1, True) + after = MODULE.t2_fprint_runtime.RuntimeProjection((), 0, True) + backend._collect_runtime_projection = AsyncMock(side_effect=(before, after)) + + with mock.patch.object(MODULE.t2_performance, "emit"): + self.assertIs(await backend.runtime_projection(), before) + backend.system_sleep_changed(True) + await backend.native_worker_sleep_task + authority.selected.linux_account_generation = "account-b" + backend.system_sleep_changed(False) + await backend.runtime_warm_task + self.assertIs(await backend.runtime_projection(), after) + self.assertEqual(backend._collect_runtime_projection.await_count, 2) + + async def test_collection_straddling_sleep_does_not_publish(self): + backend, authority = self.sleep_cache_backend() + backend.warm_runtime = AsyncMock() + entered = asyncio.Event() + release = asyncio.Event() + straddling = MODULE.t2_fprint_runtime.RuntimeProjection(("finger-1",), 1, True) + fresh = MODULE.t2_fprint_runtime.RuntimeProjection(("finger-2",), 1, True) + calls = [] + + async def collect(selected_authority): + calls.append(selected_authority) + if len(calls) == 1: + entered.set() + await release.wait() + return straddling + return fresh + + backend._collect_runtime_projection = collect + with mock.patch.object(MODULE.t2_performance, "emit"): + reader = asyncio.create_task(backend.runtime_projection()) + await asyncio.wait_for(entered.wait(), 1) + backend.system_sleep_changed(True) + await backend.native_worker_sleep_task + backend.system_sleep_changed(False) + await backend.runtime_warm_task + release.set() + self.assertIs(await asyncio.wait_for(reader, 1), straddling) + self.assertIsNone(backend.inventory_projection) + self.assertIs(await backend.runtime_projection(), fresh) + self.assertEqual(calls, [authority, authority]) + + async def test_resume_warmup_prepares_worker_without_recollecting(self): + backend, authority = self.sleep_cache_backend() + projection = MODULE.t2_fprint_runtime.RuntimeProjection(("finger-1",), 1, True) + backend._collect_runtime_projection = AsyncMock(return_value=projection) + backend._ensure_native_worker = AsyncMock() + + with mock.patch.object(MODULE.t2_performance, "emit") as emit: + await backend.warm_runtime() + backend._collect_runtime_projection.assert_awaited_once_with(authority) + backend._ensure_native_worker.assert_awaited_once_with() + backend.system_sleep_changed(True) + await backend.native_worker_sleep_task + emit.reset_mock() + backend.system_sleep_changed(False) + await backend.runtime_warm_task + + backend._collect_runtime_projection.assert_awaited_once_with(authority) + self.assertEqual(backend._ensure_native_worker.await_count, 2) + phases = [call.args[:2] for call in emit.call_args_list] + self.assertEqual(phases, [("inventory", "presentation_cache")]) + async def test_sleep_quiescence_drains_inflight_inventory_cleanup(self): backend = MODULE.T2Backend.__new__(MODULE.T2Backend) backend.system_sleeping = False