Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion docs/FPRINT_INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
57 changes: 57 additions & 0 deletions docs/evaluations/touchid-resume-presentation-cache-2026-10-27.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 5 additions & 1 deletion src/t2-fprintd.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
130 changes: 128 additions & 2 deletions tests/test_t2_fprintd.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down