From 8e1fa0fb57cce61985d51a69998699a1250e7119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 12:10:38 +0000 Subject: [PATCH 1/7] Report project exception messages in the enrollment worker failure line The enrollment worker logged only the exception class names and an authorization reason, so a Catacomb persistence failure appeared as "classes=...>CatacombBridgeError reason=unclassified" and could not be told apart from the other bridge checks. Add a JSON "detail=" list with the messages of exceptions raised by t2_* modules along the cause chain. Those messages are fixed strings; foreign exceptions are dropped and the text is bounded to printable ASCII, so the line still carries no identifiers or raw bridge replies. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh7nvcZfcnceC8vskKu --- CHANGELOG.md | 10 ++ src/t2-fprint-enrollment-worker.py | 35 +++++- tests/test_fprint_enrollment_worker_report.py | 113 ++++++++++++++++++ 3 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 tests/test_fprint_enrollment_worker_report.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e8199cc..06d055a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +### Changed + +- Report the messages of the project's own exception chain in the enrollment + worker's `enrollment stopped` line as a JSON `detail=` list, alongside the + existing class and reason fields. Only messages raised by `t2_*` modules are + included, so the line still carries no identifiers or raw bridge replies. + Without it, a Catacomb persistence failure logged only + `classes=...>CatacombBridgeError reason=unclassified`, which cannot be told + apart from the other bridge checks when reporting an issue. + ## 0.1.2 - 2026-10-28 On our test Mac, after T2Touch had run in Linux, macOS removed the account's diff --git a/src/t2-fprint-enrollment-worker.py b/src/t2-fprint-enrollment-worker.py index 418bd21..cfa7fbe 100644 --- a/src/t2-fprint-enrollment-worker.py +++ b/src/t2-fprint-enrollment-worker.py @@ -5,6 +5,7 @@ from __future__ import annotations import argparse +import json import os import sys from pathlib import Path @@ -25,6 +26,37 @@ def _exception_classes(error: BaseException) -> str: return ">".join(names) +# Messages raised by the project's own exception classes are fixed strings +# with no identifiers, so they are safe to log. Anything else (OSError text, +# socket errors, third-party exceptions) is dropped. +_DETAIL_MODULE_PREFIX = "t2_" +_DETAIL_MAX_MESSAGE = 120 +_DETAIL_MAX_MESSAGES = 6 + + +def _exception_detail(error: BaseException) -> str: + messages: list[str] = [] + current: BaseException | None = error + seen: set[int] = set() + while ( + current is not None + and id(current) not in seen + and len(messages) < _DETAIL_MAX_MESSAGES + ): + seen.add(id(current)) + module = type(current).__module__ + if isinstance(module, str) and module.startswith(_DETAIL_MODULE_PREFIX): + text = "".join( + character + for character in str(current)[:_DETAIL_MAX_MESSAGE] + if character.isascii() and character.isprintable() + ) + messages.append(text or "") + cause = current.__cause__ + current = cause if isinstance(cause, BaseException) else None + return json.dumps(messages, separators=(",", ":")) + + def _authorization_reason(error: BaseException) -> str: allowed = { "authorization login session differs from the claim": "session-changed", @@ -63,7 +95,8 @@ def main() -> int: print( "t2-fprint-enrollment-worker: enrollment stopped " f"stage={stage} classes={_exception_classes(error)} " - f"reason={_authorization_reason(error)}", + f"reason={_authorization_reason(error)} " + f"detail={_exception_detail(error)}", file=sys.stderr, ) return 1 diff --git a/tests/test_fprint_enrollment_worker_report.py b/tests/test_fprint_enrollment_worker_report.py new file mode 100644 index 0000000..17b45df --- /dev/null +++ b/tests/test_fprint_enrollment_worker_report.py @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: GPL-2.0-only +import importlib.util +import json +import sys +import unittest +from pathlib import Path + + +SOURCE = Path(__file__).parents[1] / "src" +sys.path.insert(0, str(SOURCE)) +SPEC = importlib.util.spec_from_file_location( + "t2_fprint_enrollment_worker", SOURCE / "t2-fprint-enrollment-worker.py" +) +MODULE = importlib.util.module_from_spec(SPEC) +assert SPEC.loader +SPEC.loader.exec_module(MODULE) + +import t2_catacomb_bridge as catacomb_bridge +import t2_catacomb_protocol as catacomb_protocol +import t2_enrollment_persistence_operation as persistence_operation +import t2_fprint_worker as fprint_worker + + +def _chain(*errors: BaseException) -> BaseException: + """Link errors so that errors[0].__cause__ is errors[1], and so on.""" + for outer, inner in zip(errors, errors[1:]): + outer.__cause__ = inner + return errors[0] + + +class EnrollmentWorkerReportTests(unittest.TestCase): + def test_detail_reports_project_messages_along_the_cause_chain(self): + error = _chain( + fprint_worker.FprintWorkerError( + "enrollment stopped", stage="recover-terminal-identity" + ), + persistence_operation.PersistenceOperationError( + "Catacomb persistence stopped at prepare; reconciliation is required" + ), + catacomb_bridge.CatacombBridgeError( + "Catacomb command emitted an unexpected service event" + ), + ) + self.assertEqual( + MODULE._exception_classes(error), + "FprintWorkerError>PersistenceOperationError>CatacombBridgeError", + ) + self.assertEqual( + json.loads(MODULE._exception_detail(error)), + [ + "enrollment stopped", + "Catacomb persistence stopped at prepare; reconciliation is required", + "Catacomb command emitted an unexpected service event", + ], + ) + + def test_detail_includes_protocol_errors_and_drops_foreign_messages(self): + error = _chain( + fprint_worker.FprintWorkerError("enrollment stopped"), + catacomb_bridge.CatacombBridgeError("Catacomb prepare reply is invalid"), + catacomb_protocol.CatacombProtocolError( + "Catacomb prepare returned nonzero status" + ), + OSError(111, "Connection refused: /run/t2-touchid/private/socket"), + ValueError("expected message frame, received type 7"), + ) + self.assertEqual( + json.loads(MODULE._exception_detail(error)), + [ + "enrollment stopped", + "Catacomb prepare reply is invalid", + "Catacomb prepare returned nonzero status", + ], + ) + + def test_detail_sanitizes_and_bounds_messages(self): + long_message = "x" * 500 + error = _chain( + fprint_worker.FprintWorkerError("tab\there\nnewline é end"), + catacomb_bridge.CatacombBridgeError(long_message), + catacomb_bridge.CatacombBridgeError(""), + ) + detail = json.loads(MODULE._exception_detail(error)) + self.assertEqual(detail[0], "tabherenewline end") + self.assertEqual(detail[1], "x" * MODULE._DETAIL_MAX_MESSAGE) + self.assertEqual(detail[2], "") + + def test_detail_stops_at_the_message_limit_and_on_cycles(self): + errors = [ + catacomb_bridge.CatacombBridgeError(f"message {index}") + for index in range(MODULE._DETAIL_MAX_MESSAGES + 3) + ] + _chain(*errors) + self.assertEqual( + len(json.loads(MODULE._exception_detail(errors[0]))), + MODULE._DETAIL_MAX_MESSAGES, + ) + first = catacomb_bridge.CatacombBridgeError("first") + second = catacomb_bridge.CatacombBridgeError("second") + first.__cause__ = second + second.__cause__ = first + self.assertEqual( + json.loads(MODULE._exception_detail(first)), ["first", "second"] + ) + + def test_detail_without_project_errors_is_an_empty_list(self): + self.assertEqual( + MODULE._exception_detail(RuntimeError("/etc/t2-touchid.conf")), "[]" + ) + + +if __name__ == "__main__": + unittest.main() From 0b1a094248f364ea5d84d66a7798c50d4ef4d805 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 12:20:22 +0000 Subject: [PATCH 2/7] Reconcile a lost first identity after a cold bridgeOS restart A Linux-only first enrollment can confirm and stage user_.cat and then stop at the master.cat prepare request with nothing committed on the host (observed on MacBookPro16,3 / bridgeOS 24P6005). The journal stays outcome-unknown and blocks every further enrollment, and no recovery command accepts that shape: recover-outcome refused the staged prepare directory, and even after a cold bridgeOS restart returned the SEP to the pre-enrollment surface the E3 bootstrap rule rejected a zero Catacomb UUID as invalid. Admit the exact returned-to-baseline case. The E3 classifier accepts a bootstrap baseline whose live Catacomb is absent again when no identity remains and nothing else changed. The journal forgets a witnessed identity on a no-change recovery only when its persistence failure left host commit impossible. recover-outcome discards the staged user file only once the fresh inventory already shows the empty baseline, because while bridgeOS is warm that file is the sole durable copy of the fingerprint. Everything else is still left for manual review. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh7nvcZfcnceC8vskKu --- CHANGELOG.md | 12 + docs/TROUBLESHOOTING.md | 26 ++ src/t2-native-enroll.py | 56 +++- src/t2_enrollment_journal.py | 14 + src/t2_enrollment_reconciliation.py | 15 +- tests/test_enrollment_reconciliation.py | 298 ++++++++++++++++++++++ tests/test_native_enrollment_authority.py | 155 ++++++++++- 7 files changed, 561 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06d055a..43db73e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +### Fixed + +- Let `recover-outcome` close a first enrollment whose master Catacomb save + stopped at its prepare request after a cold bridgeOS restart removed the + never-committed identity. The E3 classifier now admits a bootstrap baseline + that returned to the absent-Catacomb surface, the journal forgets a witnessed + identity only when its persistence failure left nothing on the host, and the + staged `user_.cat` is discarded only once the live inventory already + shows the empty baseline. Previously the bootstrap Catacomb UUID rule + rejected that surface, so the journal stayed `outcome-unknown` and blocked + every further enrollment with no supported way out. + ### Changed - Report the messages of the project's own exception chain in the enrollment diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index f2855ec..19edea9 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -368,6 +368,32 @@ The installed services own Bridge network preparation, discovery, authority activation, and reconciliation. Manual keybag-loading sequences from early research are not installation prerequisites. +## First enrollment saved the user Catacomb but not the master + +On a Linux-only install the first enrollment creates the whole Catacomb +generation. `t2-touchid-manage status` then shows `new_mutation_blocked: true` +with every listed category at zero, and the enrollment journal ends with +`CATACOMB_CONFIRMED` for `user_.cat` followed by +`CATACOMB_PERSISTENCE_OUTCOME_UNKNOWN` for `master.cat` at +`stage=prepare` with `host_commit_possible=False`. The worker's +`enrollment stopped` line carries the failing bridge check in `detail=`. +Locally, `/var/lib/t2-touchid/catacomb/prepare/` holds only the staged user +file and no `commit/` directory exists. + +The SEP still holds the new identity, but nothing was committed on the host. +While bridgeOS stays warm, that staged file is the only durable copy of the +fingerprint; do not remove it, and do not rerun enrollment. No command finishes +this save. Report the `detail=` text with the journal milestones. + +If you accept re-enrolling that finger, a cold bridgeOS restart returns the +SEP to the pre-enrollment surface (no identities, no Catacomb, master at state +1). After such a restart, `sudo t2-touchid-enroll recover-outcome` proves the +SEP and host both equal the baseline, discards the staged user file, and +closes the journal as a no-change recovery. It refuses while the SEP still +reports the identity or a Catacomb, so a warm restart changes nothing and the +staged file stays in place. Enrollment is unblocked once `status` reports the +mutation as complete. + ## Deletion failed and enrollment is now blocked A deletion error can mean SEP removed the fingerprint but local persistence did diff --git a/src/t2-native-enroll.py b/src/t2-native-enroll.py index e45a8ba..c8e37dd 100755 --- a/src/t2-native-enroll.py +++ b/src/t2-native-enroll.py @@ -1956,8 +1956,8 @@ def _run_outcome_unknown_reconciliation( live = t2_bridge_inventory.collect_stable_private_inventory( lease, selected.apple_uid ) - local_prepare_discarded = ( - _discard_cancelled_biolockout_prepare(store, history) + local_prepare_discarded = _discard_recoverable_prepare( + store, history, live ) host = t2_enrollment_finalizer.read_local_host_snapshot( store, history.baseline @@ -1989,18 +1989,29 @@ def _run_outcome_unknown_reconciliation( os.close(lock_descriptor) -def _discard_cancelled_biolockout_prepare( +def _discard_recoverable_prepare( store: t2_catacomb_store.CatacombStore, history: t2_enrollment_journal.EnrollmentHistory, + live: dict[str, object], ) -> bool: - """Remove the empty rollback side left by an ambiguous cancel save. - - Mesa cancellation is already terminal and identity-free at this point. - The BioLockout save request is a read/export operation, but a lost reply - can leave the host transaction directory open before any component bytes - exist. Never replay that request. Admit only the exact cancelled, - BioLockout-only, pre-host-stage shape and let the fresh stable inventory - plus normal E3 classifier prove that the identity set stayed unchanged. + """Remove a journal-bound rollback-side transaction before E3 read-back. + + Two exact shapes are admitted; anything else is left for the maintainer. + + Cancelled BioLockout save: Mesa cancellation is already terminal and + identity-free at this point. The BioLockout save request is a read/export + operation, but a lost reply can leave the host transaction directory open + before any component bytes exist. Never replay that request. Admit only + the cancelled, BioLockout-only, pre-host-stage shape and let the fresh + stable inventory plus normal E3 classifier prove that the identity set + stayed unchanged. + + Lost first identity: the user Catacomb was staged and confirmed, the + master save stopped at its prepare request with nothing committed on the + host, and a later cold bridgeOS restart removed the never-persisted + identity. The fresh inventory must already show the empty baseline + surface before the staged user file is discarded, because while the SEP + still holds the identity that file is the only durable copy of it. """ prepare = CATACOMB_ROOT / "prepare" commit = CATACOMB_ROOT / "commit" @@ -2009,6 +2020,29 @@ def _discard_cancelled_biolockout_prepare( if not prepare_pending and not commit_pending: return False persistence = history.persistence + user_name = f"user_{history.baseline['apple_uid']:08x}.cat" + staged = dict(persistence.staged_files) + lost_first_identity = ( + history.phase is t2_enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN + and history.terminal_identity_uuid is not None + and persistence.phase + is t2_enrollment_persistence_journal.PersistencePhase.OUTCOME_UNKNOWN + and persistence.outcome_unknown_stage == "prepare" + and persistence.outcome_unknown_host_commit_possible is False + and persistence.batch_index == 0 + and persistence.component_index == 1 + and len(persistence.batches) >= 1 + and [name for name, _digest in persistence.batches[0]] + == [user_name, "master.cat"] + and set(staged) == {user_name} + and live.get("per_user_identity_records") == [] + and live.get("global_identity_records") == [] + and isinstance(live.get("catacomb"), dict) + and live["catacomb"].get("present") is False + ) + if lost_first_identity and prepare_pending and not commit_pending: + store.discard_prepare({user_name}, staged) + return True exact_cancel_save = ( history.phase is t2_enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN and history.terminal_identity_uuid is None diff --git a/src/t2_enrollment_journal.py b/src/t2_enrollment_journal.py index e099268..c58bb43 100644 --- a/src/t2_enrollment_journal.py +++ b/src/t2_enrollment_journal.py @@ -748,6 +748,20 @@ def validate_history(records: list[dict[str, Any]]) -> EnrollmentHistory: raise EnrollmentJournalError( "outcome-unknown recovery observed a persistent identity delta" ) + elif terminal_identity_uuid is not None: + # E2 saw the identity, but the fresh-generation read-back now + # proves the SEP and host both equal the baseline: the identity + # was lost before any host commit (for example at a cold + # bridgeOS restart). Nothing remains to verify after reboot. + if ( + persistence.phase + is not persistence_journal.PersistencePhase.OUTCOME_UNKNOWN + or persistence._outcome_unknown_host_commit_possible is not False + ): + raise EnrollmentJournalError( + "witnessed identity vanished without an uncommitted persistence failure" + ) + terminal_identity_uuid = None reconciled_snapshot_sha256 = evidence["snapshot_sha256"] phase = EnrollmentPhase.RECONCILED continue diff --git a/src/t2_enrollment_reconciliation.py b/src/t2_enrollment_reconciliation.py index cfd1431..fab65b0 100644 --- a/src/t2_enrollment_reconciliation.py +++ b/src/t2_enrollment_reconciliation.py @@ -547,7 +547,20 @@ def classify( raise EnrollmentReconciliationError("host component metadata changed") if bootstrap: baseline_catacomb_uuid = baseline["sep_catacomb"]["uuid"] - if uuid.UUID(baseline_catacomb_uuid).int == 0: + # A first enrollment that never committed a host component can be + # followed by a cold bridgeOS restart, after which the SEP again + # reports no Catacomb at all. That is the baseline surface, not a new + # generation, so it is admitted only when nothing else changed either. + returned_to_absent_baseline = ( + not catacomb_present + and not live_after + and not added + and baseline["sep_catacomb"]["present"] is False + and catacomb["uuid"] == baseline_catacomb_uuid + ) + if returned_to_absent_baseline: + invalid_bootstrap_uuid = False + elif uuid.UUID(baseline_catacomb_uuid).int == 0: invalid_bootstrap_uuid = ( uuid.UUID(catacomb["uuid"]).int == 0 or catacomb["uuid"] == baseline_catacomb_uuid diff --git a/tests/test_enrollment_reconciliation.py b/tests/test_enrollment_reconciliation.py index ec35de2..2d15035 100644 --- a/tests/test_enrollment_reconciliation.py +++ b/tests/test_enrollment_reconciliation.py @@ -962,5 +962,303 @@ def test_identity_event_without_changed_persistence_is_rejected(self): ) + def create_lost_first_identity(self, directory: str) -> tuple[Path, str, dict]: + """A bootstrap enrollment whose master save stopped at its prepare request. + + This is the journal shape observed on MacBookPro16,3 / bridgeOS 24P6005: + the user Catacomb was confirmed and staged, then the master prepare + reply failed validation before any host commit. + """ + value = baseline() + value.update( + { + "baseline_version": 2, + "identity_records": [], + "capacity": {"used": 0, "maximum": 5}, + "sep_catacomb": { + "present": False, + "uuid": str(uuid.UUID(int=0)), + "hash": None, + }, + "host_components": [], + "master_enrollment_count": 0, + "backup_references": [], + } + ) + generation = value["connection_generation"] + path = Path(directory) / "operation.jsonl" + operation_id, _record = mutation_journal.create(path, "enroll", value) + enrollment_journal.append_checked( + path, + operation_id, + "ENROLL_START_INTENT", + { + "apple_uid": 501, + "protocol_version": 2, + "connection_generation": generation, + "request_length": 68, + "request_sha256": "a" * 64, + }, + ) + enrollment_journal.append_checked( + path, operation_id, "ENROLL_START_OBSERVED", {"status": 0} + ) + enrollment_journal.append_checked( + path, + operation_id, + "E2_TERMINAL_RESULT_WITNESSED", + { + "connection_generation": generation, + "event_sequence": 1, + "envelope_type": enrollment_journal.SERVICE_ENROLLMENT_RESULT, + "event_version": 2, + "payload_length": 40, + "event_sha256": "b" * 64, + "embedded_user_matches": True, + }, + ) + enrollment_journal.append_checked( + path, + operation_id, + "E2_WITNESS_IDENTITY_READBACK_OBSERVED", + { + "connection_generation": generation, + "user_id": 501, + "identity_uuid": str(uuid.UUID(int=8)), + "source": "stable-readback", + "single_identity_added": True, + "host_unchanged": True, + "sep_catacomb_advanced": True, + "per_user_global_equal": True, + "mapping_generation": value["mapping_generation"], + }, + ) + enrollment_journal.append_checked( + path, + operation_id, + "CATACOMB_PERSISTENCE_PLAN", + { + "connection_generation": generation, + "batches": [ + [ + {"name": "user_000001f5.cat", "descriptor_sha256": "1" * 64}, + {"name": "master.cat", "descriptor_sha256": "2" * 64}, + ], + [{"name": "biolockout.cat", "descriptor_sha256": "3" * 64}], + ], + }, + ) + user = _component_ref(0, 0, "user_000001f5.cat", "1" * 64) + enrollment_journal.append_checked( + path, operation_id, "CATACOMB_PREPARE_INTENT", user + ) + enrollment_journal.append_checked( + path, + operation_id, + "CATACOMB_PREPARED", + {**user, "status": 0, "expected_blob_length": 15902}, + ) + enrollment_journal.append_checked( + path, operation_id, "CATACOMB_COMPLETE_INTENT", user + ) + enrollment_journal.append_checked( + path, + operation_id, + "CATACOMB_SECURE_BLOB_CAPTURED", + { + **user, + "status": 0, + "blob_length": 15902, + "secure_blob_sha256": "4" * 64, + }, + ) + enrollment_journal.append_checked( + path, + operation_id, + "CATACOMB_HOST_STAGED", + {**user, "secure_blob_sha256": "4" * 64, "final_file_sha256": "7" * 64}, + ) + enrollment_journal.append_checked( + path, operation_id, "CATACOMB_CONFIRM_INTENT", user + ) + enrollment_journal.append_checked( + path, operation_id, "CATACOMB_CONFIRMED", {**user, "status": 0} + ) + master = _component_ref(0, 1, "master.cat", "2" * 64) + enrollment_journal.append_checked( + path, operation_id, "CATACOMB_PREPARE_INTENT", master + ) + enrollment_journal.append_checked( + path, + operation_id, + "CATACOMB_PERSISTENCE_OUTCOME_UNKNOWN", + { + **master, + "stage": "prepare", + "reason": "transport-error", + "sep_mutation_possible": True, + "host_commit_possible": False, + }, + ) + return path, operation_id, value + + def cold_bootstrap_snapshots(self, value: dict) -> tuple[dict, dict]: + """Empty host store and the SEP surface after a cold bridgeOS restart.""" + host = { + "account_uuid": value["account_uuid"], + "bag_uuid": value["bag_uuid"], + "identity_records": [], + "host_components": [], + "master_enrollment_count": 0, + } + live = { + "double_collection_equal": True, + "connection_generation": str(uuid.UUID(int=99)), + "apple_uid": 501, + "biometric_protocol_version": 2, + "per_user_identity_records": [], + "global_identity_records": [], + "maximum_capacity": 5, + "configured_user_free_capacity": 5, + "catacomb": { + "present": False, + "uuid": str(uuid.UUID(int=0)), + "hash": "0" * 64, + }, + } + return host, live + + def test_lost_first_identity_reconciles_as_no_change_after_cold_restart(self): + with tempfile.TemporaryDirectory() as directory: + path, operation_id, value = self.create_lost_first_identity(directory) + before = enrollment_journal.read(path) + self.assertIs(before.phase, enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN) + self.assertIsNotNone(before.terminal_identity_uuid) + host, live = self.cold_bootstrap_snapshots(value) + result = reconciliation.append_reconciled( + path, + operation_id, + host=host, + live=live, + mapping_generation=value["mapping_generation"], + ) + records = mutation_journal.read(path) + self.assertEqual(result.phase, enrollment_journal.EnrollmentPhase.RECONCILED) + self.assertIsNone(result.terminal_identity_uuid) + self.assertEqual( + records[-1]["milestone"], "E3_RECOVERY_NO_CHANGE_RECONCILED" + ) + self.assertFalse(records[-1]["evidence"]["identity_present"]) + + def test_lost_first_identity_is_not_reconciled_while_sep_differs(self): + with tempfile.TemporaryDirectory() as directory: + path, operation_id, value = self.create_lost_first_identity(directory) + host, live = self.cold_bootstrap_snapshots(value) + # Warm bridgeOS: the identity and its Catacomb are still there. + live["per_user_identity_records"] = [ + {"user_id": 501, "identity_uuid": str(uuid.UUID(int=8))} + ] + live["global_identity_records"] = [ + { + "user_id": 501, + "identity_uuid": str(uuid.UUID(int=8)), + "group_type": 1, + "group_uuid": str(uuid.UUID(int=0)), + } + ] + live["configured_user_free_capacity"] = 4 + live["catacomb"] = { + "present": True, + "uuid": str(uuid.UUID(int=9)), + "hash": "3" * 64, + } + with self.assertRaisesRegex( + reconciliation.EnrollmentReconciliationError, "inventories diverge" + ): + reconciliation.append_reconciled( + path, + operation_id, + host=host, + live=live, + mapping_generation=value["mapping_generation"], + ) + # Absent Catacomb but a surviving identity is not the baseline. + host, live = self.cold_bootstrap_snapshots(value) + live["per_user_identity_records"] = [ + {"user_id": 501, "identity_uuid": str(uuid.UUID(int=8))} + ] + live["global_identity_records"] = [ + { + "user_id": 501, + "identity_uuid": str(uuid.UUID(int=8)), + "group_type": 1, + "group_uuid": str(uuid.UUID(int=0)), + } + ] + with self.assertRaisesRegex( + reconciliation.EnrollmentReconciliationError, "inventories diverge" + ): + reconciliation.append_reconciled( + path, + operation_id, + host=host, + live=live, + mapping_generation=value["mapping_generation"], + ) + # A zero Catacomb UUID that claims presence is still rejected. + host, live = self.cold_bootstrap_snapshots(value) + live["catacomb"]["present"] = True + with self.assertRaisesRegex( + reconciliation.EnrollmentReconciliationError, "Catacomb UUID is invalid" + ): + reconciliation.append_reconciled( + path, + operation_id, + host=host, + live=live, + mapping_generation=value["mapping_generation"], + ) + self.assertIs( + enrollment_journal.read(path).phase, + enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN, + ) + + def test_no_change_recovery_keeps_witnessed_identity_after_possible_commit(self): + """A vanished identity is only forgotten when nothing could have been committed.""" + with tempfile.TemporaryDirectory() as directory: + path, operation_id, value = self.create_lost_first_identity(directory) + records = mutation_journal.read(path) + # Rewrite the failure as a host-commit ambiguity of the same component. + failure = dict(records[-1]["evidence"]) + failure.update({"stage": "host-commit", "host_commit_possible": True}) + prefix = records[:-1] + rewritten = Path(directory) / "rewritten.jsonl" + rewritten_id, _record = mutation_journal.create(rewritten, "enroll", value) + # Replay the recorded chain onto the fresh file to keep the hash chain valid. + for record in prefix[1:]: + enrollment_journal.append_checked( + rewritten, rewritten_id, record["milestone"], record["evidence"] + ) + enrollment_journal.append_checked( + rewritten, rewritten_id, "CATACOMB_PERSISTENCE_OUTCOME_UNKNOWN", failure + ) + host, live = self.cold_bootstrap_snapshots(value) + with self.assertRaisesRegex( + enrollment_journal.EnrollmentJournalError, + "vanished without an uncommitted persistence failure", + ): + reconciliation.append_reconciled( + rewritten, + rewritten_id, + host=host, + live=live, + mapping_generation=value["mapping_generation"], + ) + self.assertIs( + enrollment_journal.read(rewritten).phase, + enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN, + ) + + if __name__ == "__main__": unittest.main() diff --git a/tests/test_native_enrollment_authority.py b/tests/test_native_enrollment_authority.py index 50a44aa..3d8d9fc 100644 --- a/tests/test_native_enrollment_authority.py +++ b/tests/test_native_enrollment_authority.py @@ -135,7 +135,7 @@ def test_active_outcome_unknown_reconciles_no_change_without_replay(self) -> Non ), mock.patch.object( native_enroll, - "_discard_cancelled_biolockout_prepare", + "_discard_recoverable_prepare", return_value=False, ), mock.patch.object( @@ -188,6 +188,7 @@ def test_cancel_save_ambiguity_discards_only_empty_prepare_before_readback( terminal_identity_uuid=None, terminal_status=66, persistence=persistence, + baseline={"apple_uid": 501}, ) store = SimpleNamespace(discard_empty_prepare=mock.Mock()) with mock.patch.object( @@ -195,13 +196,161 @@ def test_cancel_save_ambiguity_discards_only_empty_prepare_before_readback( "lexists", side_effect=lambda path: Path(path).name == "prepare", ): - discarded = native_enroll._discard_cancelled_biolockout_prepare( - store, history + discarded = native_enroll._discard_recoverable_prepare( + store, history, {} ) self.assertTrue(discarded) store.discard_empty_prepare.assert_called_once_with() + def _lost_first_identity_history(self, **overrides: object) -> SimpleNamespace: + """A first enrollment whose master save stopped at its prepare request.""" + + persistence = SimpleNamespace( + phase=( + native_enroll.t2_enrollment_persistence_journal.PersistencePhase.OUTCOME_UNKNOWN + ), + outcome_unknown_stage="prepare", + outcome_unknown_host_commit_possible=False, + batch_index=0, + component_index=1, + staged_files=(("user_000001f5.cat", "7" * 64),), + batches=( + (("user_000001f5.cat", "1" * 64), ("master.cat", "2" * 64)), + (("biolockout.cat", "3" * 64),), + ), + ) + for key, value in overrides.items(): + setattr(persistence, key, value) + return SimpleNamespace( + phase=native_enroll.t2_enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN, + terminal_identity_uuid=identifier(8), + terminal_status=None, + persistence=persistence, + baseline={"apple_uid": 501}, + ) + + @staticmethod + def _cold_live() -> dict[str, object]: + return { + "per_user_identity_records": [], + "global_identity_records": [], + "catacomb": {"present": False, "uuid": identifier(0), "hash": "0" * 64}, + } + + def test_lost_first_identity_discards_staged_user_only_on_empty_surface( + self, + ) -> None: + """The staged user file goes only after the SEP shows the baseline again.""" + + history = self._lost_first_identity_history() + store = SimpleNamespace( + discard_prepare=mock.Mock(), discard_empty_prepare=mock.Mock() + ) + with mock.patch.object( + native_enroll.os.path, + "lexists", + side_effect=lambda path: Path(path).name == "prepare", + ): + discarded = native_enroll._discard_recoverable_prepare( + store, history, self._cold_live() + ) + + self.assertTrue(discarded) + store.discard_prepare.assert_called_once_with( + {"user_000001f5.cat"}, {"user_000001f5.cat": "7" * 64} + ) + store.discard_empty_prepare.assert_not_called() + + def test_lost_first_identity_keeps_staged_user_while_sep_holds_identity( + self, + ) -> None: + """A warm bridgeOS still holds the identity; the staged file is its only copy.""" + + history = self._lost_first_identity_history() + store = SimpleNamespace( + discard_prepare=mock.Mock(), discard_empty_prepare=mock.Mock() + ) + warm_variants = [ + { + **self._cold_live(), + "per_user_identity_records": [ + {"user_id": 501, "identity_uuid": identifier(8)} + ], + }, + { + **self._cold_live(), + "catacomb": {"present": True, "uuid": identifier(9), "hash": "3" * 64}, + }, + {}, + ] + for live in warm_variants: + with ( + self.subTest(live=live), + mock.patch.object( + native_enroll.os.path, + "lexists", + side_effect=lambda path: Path(path).name == "prepare", + ), + self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, + "unsupported local Catacomb transaction", + ), + ): + native_enroll._discard_recoverable_prepare(store, history, live) + store.discard_prepare.assert_not_called() + store.discard_empty_prepare.assert_not_called() + + def test_lost_first_identity_requires_the_exact_persistence_shape(self) -> None: + """Any other stage, component, or staged set is left for manual review.""" + + store = SimpleNamespace( + discard_prepare=mock.Mock(), discard_empty_prepare=mock.Mock() + ) + variants = { + "complete stage": {"outcome_unknown_stage": "complete"}, + "host commit possible": {"outcome_unknown_host_commit_possible": True}, + "user component": {"component_index": 0}, + "nothing staged": {"staged_files": ()}, + "master staged too": { + "staged_files": ( + ("user_000001f5.cat", "7" * 64), + ("master.cat", "8" * 64), + ) + }, + "other user staged": {"staged_files": (("user_000001f6.cat", "7" * 64),)}, + } + for label, overrides in variants.items(): + history = self._lost_first_identity_history(**overrides) + with ( + self.subTest(label), + mock.patch.object( + native_enroll.os.path, + "lexists", + side_effect=lambda path: Path(path).name == "prepare", + ), + self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, + "unsupported local Catacomb transaction", + ), + ): + native_enroll._discard_recoverable_prepare( + store, history, self._cold_live() + ) + history = self._lost_first_identity_history() + with ( + mock.patch.object(native_enroll.os.path, "lexists", return_value=True), + self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, + "unsupported local Catacomb transaction", + ), + ): + native_enroll._discard_recoverable_prepare( + store, history, self._cold_live() + ) + store.discard_prepare.assert_not_called() + store.discard_empty_prepare.assert_not_called() + def test_exact_interrupted_authority_temp_is_resumed(self) -> None: """Only byte-identical publication state may cross the atomic rename.""" From 9eef3eb08da5871c9fd57aeaf81129e7080cb29b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 15:36:25 +0000 Subject: [PATCH 3/7] Let fprintd start after a no-change first enrollment is reconciled The post-reboot reconciler skipped external-deletion reconciliation only when the mutation directory was empty. After recover-outcome closes a first enrollment that never kept its identity, the completed journal is retained, so the reconciler ran t2-touchid-manage reconcile-external-deletion-if-needed, which needs the per-user E4 authority that a first enrollment never published. The child exited 1 with an unmapped message, fprintd failed its dependency at every start, and the account could never enrol again. Treat retained enrollment journals that are complete and proved no SEP change (baseline-reconciled, aborted-before-start, or reconciled with no terminal identity and no post-reboot verification pending) as part of the initial no-op state. Any other journal kind, an unfinished or post-reboot-pending entry, an unreadable journal, Catacomb bytes, per-user history or an authority manifest still go through reconciliation. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh5eb1bKqSt7Ec1CdVV --- CHANGELOG.md | 9 +++ docs/FIRST_RUN_RECOVERY.md | 8 ++- docs/TROUBLESHOOTING.md | 8 +++ src/t2_native_post_reboot_reconciler.py | 39 +++++++++++- tests/test_post_reboot_reconciler.py | 80 +++++++++++++++++++++++++ 5 files changed, 139 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 43db73e..f6b1b6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Fixed +- Let fprintd start again after `recover-outcome` closes a first enrollment + that changed nothing. The post-reboot reconciler treated any retained + mutation journal as evidence requiring external-deletion reconciliation, + but that child command needs the per-user enrollment authority, which does + not exist before the first fingerprint is kept. The startup no-op now also + covers retained enrollment journals that are complete and proved no SEP + change, while any other journal kind, an unfinished or post-reboot-pending + entry, Catacomb bytes, per-user history or an authority manifest still go + through reconciliation. - Let `recover-outcome` close a first enrollment whose master Catacomb save stopped at its prepare request after a cold bridgeOS restart removed the never-committed identity. The E3 classifier now admits a bootstrap baseline diff --git a/docs/FIRST_RUN_RECOVERY.md b/docs/FIRST_RUN_RECOVERY.md index 0a5d7f1..68fc8ee 100644 --- a/docs/FIRST_RUN_RECOVERY.md +++ b/docs/FIRST_RUN_RECOVERY.md @@ -23,9 +23,11 @@ The request does not authorize creating or deleting an identity. After this recovery, a separate first-enrollment startup gate could still stop fprintd: automatic external-deletion reconciliation required an enrollment authority before the first fingerprint could be enrolled. Reconciliation now -returns a no-op only when the account has no authority manifest, mutation -history, Catacomb state, or retained enrollment journals. Existing or dangling -authority manifests and retained state still go through reconciliation. The +returns a no-op only when the account has no authority manifest, Catacomb +state, or retained per-user history, and when every retained mutation journal +is an enrollment that completed without changing the SEP identity set (for +example one closed by `recover-outcome`). Existing or dangling authority +manifests and any other retained state still go through reconciliation. The external-deletion diagnostic stage is also registered so a child failure keeps its bounded stage and exit status instead of being masked by `ValueError`. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 19edea9..141f666 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -394,6 +394,14 @@ reports the identity or a Catacomb, so a warm restart changes nothing and the staged file stays in place. Enrollment is unblocked once `status` reports the mutation as complete. +The closed journal stays under `/var/lib/t2-touchid/mutations/`. Because the +first enrollment never published the per-user authority, +`t2-touchid-post-reboot.service` used to treat that retained journal as state +needing external-deletion reconciliation, a child command that cannot run +without the authority, so fprintd failed its dependency at every start with +`reason: null`. The post-reboot reconciler now recognises a complete no-change +enrollment journal as part of the initial state and lets fprintd start. + ## Deletion failed and enrollment is now blocked A deletion error can mean SEP removed the fingerprint but local persistence did diff --git a/src/t2_native_post_reboot_reconciler.py b/src/t2_native_post_reboot_reconciler.py index 5220f25..105866d 100644 --- a/src/t2_native_post_reboot_reconciler.py +++ b/src/t2_native_post_reboot_reconciler.py @@ -28,6 +28,14 @@ SOURCE_ROOT = Path(__file__).resolve().parent MUTATION_ROOT = t2_post_reboot_reconciler.MUTATION_ROOT CATACOMB_ROOT = Path("/var/lib/t2-touchid/catacomb") +# Enrollment phases whose journals prove the SEP identity set did not change. +_NO_CHANGE_ENROLLMENT_PHASES = frozenset( + { + t2_enrollment_journal.EnrollmentPhase.BASELINE.value, + t2_enrollment_journal.EnrollmentPhase.ABORTED_BEFORE_START.value, + t2_enrollment_journal.EnrollmentPhase.RECONCILED.value, + } +) class NativePostRebootReconcilerError(RuntimeError): @@ -329,6 +337,29 @@ def _verify_management( return document +def _retains_only_no_change_enrollments(root: Path) -> bool: + """True when every retained journal is an enrollment that changed nothing. + + A reconciled enrollment whose identity never existed (or never survived) + is complete evidence that the SEP returned to its baseline. Any other + kind, an unfinished or post-reboot-pending entry, or an unreadable journal + still requires reconciliation. + """ + if not any(root.iterdir()): + return True + try: + entries = t2_mutation_registry.scan(root) + except t2_mutation_registry.MutationRegistryError: + return False + return all( + entry.kind == "enroll" + and entry.phase in _NO_CHANGE_ENROLLMENT_PHASES + and not entry.blocks_new_mutation + and not entry.post_reboot_pending + for entry in entries + ) + + def reconcile_external_deletion_if_needed( *, runner: Callable[..., object] = subprocess.run ) -> NativePostRebootReconcilerResult: @@ -348,11 +379,15 @@ def reconcile_external_deletion_if_needed( # A newly activated account has no enrollment authority or Catacomb yet. # External deletion reconciliation requires an earlier enrollment; making # it a prerequisite here prevents fprintd from accepting the first one. - # Only the empty initial state is a no-op. Retained mutation/Catacomb + # Only the initial state is a no-op: no manifest, no Catacomb bytes, no + # per-user history, and no mutation journal other than enrollments proven + # to have changed nothing. Without an authority the child below cannot + # open a management lease, so a retained no-change journal would otherwise + # stop fprintd forever before the first fingerprint. Retained Catacomb # evidence or an existing (even dangling) manifest still needs validation. if ( not os.path.lexists(user_root / "authority.json") - and not any(MUTATION_ROOT.iterdir()) + and _retains_only_no_change_enrollments(MUTATION_ROOT) and not any(CATACOMB_ROOT.iterdir()) and not any(user_root.glob("*.jsonl")) ): diff --git a/tests/test_post_reboot_reconciler.py b/tests/test_post_reboot_reconciler.py index 3c5b066..63e5df3 100644 --- a/tests/test_post_reboot_reconciler.py +++ b/tests/test_post_reboot_reconciler.py @@ -194,6 +194,86 @@ def test_external_reconciliation_skips_only_empty_initial_state(self): self.assertEqual(failure["child_exit_status"], 17) runner.assert_called_once() + def test_external_reconciliation_skips_retained_no_change_enrollments(self): + mapping_set = SimpleNamespace( + mappings=(SimpleNamespace(enabled=True, linux_uid=1000),) + ) + registry = native_reconciler.t2_mutation_registry + no_change = registry.MutationEntry("enroll", "reconciled", False, False) + aborted = registry.MutationEntry("enroll", "aborted-before-start", False, False) + cases = { + "reconciled-no-change": ((no_change,), True), + "two-no-change": ((no_change, aborted), True), + "reconciled-awaiting-reboot": ((registry.MutationEntry("enroll", "reconciled", False, True),), False), + "outcome-unknown": ((registry.MutationEntry("enroll", "outcome-unknown", True, False),), False), + "verified-without-manifest": ((registry.MutationEntry("enroll", "addition-verified", False, False),), False), + "complete-delete": ((registry.MutationEntry("delete-one", "reconciled", False, False),), False), + "mixed": ((no_change, registry.MutationEntry("rename", "reconciled", False, False)), False), + "unreadable": (registry.MutationRegistryError("mutation journal is invalid"), False), + } + for name, (entries, skipped) in cases.items(): + with self.subTest(case=name), tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + users = root / "users" + mutations = root / "mutations" + catacomb = root / "catacomb" + for directory in (users / "1000", mutations, catacomb): + directory.mkdir(parents=True) + (mutations / f"{uuid.UUID(int=1)}.jsonl").touch() + runner = mock.Mock(return_value=SimpleNamespace(returncode=17)) + scan = mock.Mock(side_effect=entries) if isinstance(entries, Exception) else mock.Mock(return_value=entries) + with ( + mock.patch.object(native_reconciler.t2_user_mapping, "load", return_value=mapping_set), + mock.patch.object(native_reconciler.t2_user_authority, "USERS_ROOT", users), + mock.patch.object(native_reconciler, "MUTATION_ROOT", mutations), + mock.patch.object(native_reconciler, "CATACOMB_ROOT", catacomb), + mock.patch.object(registry, "scan", scan), + ): + if skipped: + result = native_reconciler.reconcile_external_deletion_if_needed(runner=runner) + self.assertEqual(result.state, "no-pending-mutation") + self.assertFalse(result.journal_updated) + runner.assert_not_called() + else: + with self.assertRaises(post_reboot_diagnostic.PostRebootStageError): + native_reconciler.reconcile_external_deletion_if_needed(runner=runner) + runner.assert_called_once() + scan.assert_called_once_with(mutations) + + def test_retained_no_change_enrollment_still_defers_to_other_retained_state(self): + mapping_set = SimpleNamespace( + mappings=(SimpleNamespace(enabled=True, linux_uid=1000),) + ) + registry = native_reconciler.t2_mutation_registry + no_change = (registry.MutationEntry("enroll", "reconciled", False, False),) + for retained in ("manifest", "catacomb", "journal"): + with self.subTest(retained=retained), tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + users = root / "users" + user = users / "1000" + mutations = root / "mutations" + catacomb = root / "catacomb" + for directory in (user, mutations, catacomb): + directory.mkdir(parents=True) + (mutations / f"{uuid.UUID(int=1)}.jsonl").touch() + if retained == "manifest": + (user / "authority.json").write_text("invalid") + elif retained == "catacomb": + (catacomb / "prepare").mkdir() + else: + (user / "retained.jsonl").touch() + runner = mock.Mock(return_value=SimpleNamespace(returncode=17)) + with ( + mock.patch.object(native_reconciler.t2_user_mapping, "load", return_value=mapping_set), + mock.patch.object(native_reconciler.t2_user_authority, "USERS_ROOT", users), + mock.patch.object(native_reconciler, "MUTATION_ROOT", mutations), + mock.patch.object(native_reconciler, "CATACOMB_ROOT", catacomb), + mock.patch.object(registry, "scan", return_value=no_change), + ): + with self.assertRaises(post_reboot_diagnostic.PostRebootStageError): + native_reconciler.reconcile_external_deletion_if_needed(runner=runner) + runner.assert_called_once() + def test_failure_diagnostic_is_bounded_and_redacted(self): private = OSError(errno.EIO, "/private/identifier/payload") failure = post_reboot_diagnostic.staged( From 9b31fcb01ce74afd65a81cfe75d68ef0b249346f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 16:11:49 +0000 Subject: [PATCH 4/7] Let the first enrollment start after a no-change journal is retained fprintd's pre-E4 bootstrap projection, the enrollment worker and legacy first-run call _require_fresh_enrollment_state, which rejected any file in the mutation directory. After recover-outcome closes a first enrollment that changed nothing, the retained journal made EnrollStart fail and the desktop enrollment ended at "Enrollment stopped" with no reason, even though the service chain was healthy. Move the no-change rule into t2_mutation_registry as retains_only_no_change_enrollments and use it both there and in the post-reboot reconciler's startup no-op. Add t2_enrollment_journal.is_no_change_history and use it in the post-reboot verification, authority publication and E4 publication candidate selectors, so the retained journal neither becomes a second candidate nor counts as a later mutation once the next enrollment succeeds. Catacomb bytes, activation state, other journal kinds and unfinished or post-reboot-pending entries still require reconciliation. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh5eb1bKqSt7Ec1CdVV --- CHANGELOG.md | 24 +++--- docs/TROUBLESHOOTING.md | 6 +- src/t2-native-enroll.py | 25 +++--- src/t2_enrollment_journal.py | 16 ++++ src/t2_mutation_registry.py | 32 ++++++++ src/t2_native_post_reboot_reconciler.py | 44 ++--------- tests/test_enrollment_reconciliation.py | 4 + tests/test_mutation_registry.py | 28 +++++++ tests/test_native_enrollment_authority.py | 95 +++++++++++++++++++++++ 9 files changed, 215 insertions(+), 59 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f6b1b6d..27d03f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,15 +8,21 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Fixed -- Let fprintd start again after `recover-outcome` closes a first enrollment - that changed nothing. The post-reboot reconciler treated any retained - mutation journal as evidence requiring external-deletion reconciliation, - but that child command needs the per-user enrollment authority, which does - not exist before the first fingerprint is kept. The startup no-op now also - covers retained enrollment journals that are complete and proved no SEP - change, while any other journal kind, an unfinished or post-reboot-pending - entry, Catacomb bytes, per-user history or an authority manifest still go - through reconciliation. +- Let fprintd start and the first fingerprint enroll again after + `recover-outcome` closes a first enrollment that changed nothing. Every + pre-first-enrollment path treated any retained mutation journal as state + awaiting reconciliation: the post-reboot reconciler ran external-deletion + reconciliation, whose child needs the per-user enrollment authority that + does not exist yet, so fprintd failed its dependency at every start; and + fprintd's bootstrap projection, the enrollment worker and legacy first-run + required an empty mutation directory, so `EnrollStart` failed and the + desktop enrollment showed "Enrollment stopped" with no reason. Retained + enrollment journals that are complete and proved no SEP change (baseline, + aborted before start, or reconciled without an identity) now count as the + initial state in those checks and in the post-reboot and authority + publication candidate selectors. Any other journal kind, an unfinished or + post-reboot-pending entry, Catacomb bytes, per-user history or an authority + manifest still go through reconciliation. - Let `recover-outcome` close a first enrollment whose master Catacomb save stopped at its prepare request after a cold bridgeOS restart removed the never-committed identity. The E3 classifier now admits a bootstrap baseline diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 141f666..d0bf43b 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -399,8 +399,10 @@ first enrollment never published the per-user authority, `t2-touchid-post-reboot.service` used to treat that retained journal as state needing external-deletion reconciliation, a child command that cannot run without the authority, so fprintd failed its dependency at every start with -`reason: null`. The post-reboot reconciler now recognises a complete no-change -enrollment journal as part of the initial state and lets fprintd start. +`reason: null`. fprintd's first-enrollment bootstrap and the enrollment worker +likewise required an empty mutation directory, so `t2-touchid-enroll` ended at +"Enrollment stopped" with no reason. Those checks now recognise a complete +no-change enrollment journal as part of the initial state. ## Deletion failed and enrollment is now blocked diff --git a/src/t2-native-enroll.py b/src/t2-native-enroll.py index c8e37dd..0fb6345 100755 --- a/src/t2-native-enroll.py +++ b/src/t2-native-enroll.py @@ -329,10 +329,19 @@ def _require_fresh_enrollment_state() -> None: for path in (CATACOMB_ROOT, MUTATION_ROOT, ACTIVATION_ROOT): _private(path, directory=True) with os.scandir(path) as entries: - if any(True for _entry in entries): - raise NativeEnrollmentError( - "native first-enrollment state is not empty; reconcile retained state" - ) + if not any(True for _entry in entries): + continue + # Enrollment journals that completed without changing the SEP identity + # set (for example one closed by recover-outcome) are retained evidence + # of the initial state, not state awaiting reconciliation. + if ( + path == MUTATION_ROOT + and t2_mutation_registry.retains_only_no_change_enrollments(path) + ): + continue + raise NativeEnrollmentError( + "native first-enrollment state is not empty; reconcile retained state" + ) def _require_private_runtime_root() -> None: @@ -1574,6 +1583,8 @@ def _pending_post_reboot_journal( raise NativeEnrollmentError("native mutation directory is not canonical") path = MUTATION_ROOT / entry.name history = t2_enrollment_journal.read(path) + if t2_enrollment_journal.is_no_change_history(history): + continue if history.phase is t2_enrollment_journal.EnrollmentPhase.RECONCILED: candidates.append((path, history)) else: @@ -1630,11 +1641,7 @@ def _pending_authority_publication_journal( candidates.append((path, history)) elif ( history.baseline.get("baseline_version") != 2 - or history.phase - not in { - t2_enrollment_journal.EnrollmentPhase.BASELINE, - t2_enrollment_journal.EnrollmentPhase.ABORTED_BEFORE_START, - } + or not t2_enrollment_journal.is_no_change_history(history) ): later_mutation = True if later_mutation or len(candidates) != 1: diff --git a/src/t2_enrollment_journal.py b/src/t2_enrollment_journal.py index c58bb43..ff50af7 100644 --- a/src/t2_enrollment_journal.py +++ b/src/t2_enrollment_journal.py @@ -40,6 +40,22 @@ class EnrollmentPhase(Enum): OUTCOME_UNKNOWN = "outcome-unknown" +def is_no_change_history(history: "EnrollmentHistory") -> bool: + """True when an enrollment journal proves the SEP identity set did not change. + + A baseline-only or aborted-before-start journal never issued a command. A + reconciled journal without a terminal identity closed as a no-change + recovery, so nothing it describes survives on the SEP or the host. + """ + return history.phase in { + EnrollmentPhase.BASELINE, + EnrollmentPhase.ABORTED_BEFORE_START, + } or ( + history.phase is EnrollmentPhase.RECONCILED + and history.terminal_identity_uuid is None + ) + + @dataclass(frozen=True, repr=False) class EnrollmentHistory: operation_id: str diff --git a/src/t2_mutation_registry.py b/src/t2_mutation_registry.py index 9a57796..a562442 100644 --- a/src/t2_mutation_registry.py +++ b/src/t2_mutation_registry.py @@ -224,3 +224,35 @@ def blocks_new_mutation(root: Path, *, excluding_kind: str | None = None) -> boo and (excluding_kind is None or entry.kind != excluding_kind) for entry in scan(root) ) + + +# Enrollment phases whose journals prove the SEP identity set did not change. +NO_CHANGE_ENROLLMENT_PHASES = frozenset( + { + t2_enrollment_journal.EnrollmentPhase.BASELINE.value, + t2_enrollment_journal.EnrollmentPhase.ABORTED_BEFORE_START.value, + t2_enrollment_journal.EnrollmentPhase.RECONCILED.value, + } +) + + +def retains_only_no_change_enrollments(root: Path) -> bool: + """True when every retained journal is an enrollment that changed nothing. + + A reconciled enrollment whose identity never existed (or never survived) + is complete evidence that the SEP returned to its baseline, so the paths + that require the initial pre-enrollment state may keep such journals. Any + other kind, an unfinished or post-reboot-pending entry, or an unreadable + journal still requires reconciliation. + """ + try: + entries = scan(root) + except MutationRegistryError: + return False + return all( + entry.kind == "enroll" + and entry.phase in NO_CHANGE_ENROLLMENT_PHASES + and not entry.blocks_new_mutation + and not entry.post_reboot_pending + for entry in entries + ) diff --git a/src/t2_native_post_reboot_reconciler.py b/src/t2_native_post_reboot_reconciler.py index 105866d..9d51aa7 100644 --- a/src/t2_native_post_reboot_reconciler.py +++ b/src/t2_native_post_reboot_reconciler.py @@ -28,16 +28,6 @@ SOURCE_ROOT = Path(__file__).resolve().parent MUTATION_ROOT = t2_post_reboot_reconciler.MUTATION_ROOT CATACOMB_ROOT = Path("/var/lib/t2-touchid/catacomb") -# Enrollment phases whose journals prove the SEP identity set did not change. -_NO_CHANGE_ENROLLMENT_PHASES = frozenset( - { - t2_enrollment_journal.EnrollmentPhase.BASELINE.value, - t2_enrollment_journal.EnrollmentPhase.ABORTED_BEFORE_START.value, - t2_enrollment_journal.EnrollmentPhase.RECONCILED.value, - } -) - - class NativePostRebootReconcilerError(RuntimeError): pass @@ -176,11 +166,7 @@ def _pending_native_candidate() -> object | None: candidates.append((path, history)) elif ( history.baseline.get("baseline_version") != 2 - or history.phase - not in { - t2_enrollment_journal.EnrollmentPhase.BASELINE, - t2_enrollment_journal.EnrollmentPhase.ABORTED_BEFORE_START, - } + or not t2_enrollment_journal.is_no_change_history(history) ): later_mutation = True if interrupted_deletes: @@ -337,29 +323,6 @@ def _verify_management( return document -def _retains_only_no_change_enrollments(root: Path) -> bool: - """True when every retained journal is an enrollment that changed nothing. - - A reconciled enrollment whose identity never existed (or never survived) - is complete evidence that the SEP returned to its baseline. Any other - kind, an unfinished or post-reboot-pending entry, or an unreadable journal - still requires reconciliation. - """ - if not any(root.iterdir()): - return True - try: - entries = t2_mutation_registry.scan(root) - except t2_mutation_registry.MutationRegistryError: - return False - return all( - entry.kind == "enroll" - and entry.phase in _NO_CHANGE_ENROLLMENT_PHASES - and not entry.blocks_new_mutation - and not entry.post_reboot_pending - for entry in entries - ) - - def reconcile_external_deletion_if_needed( *, runner: Callable[..., object] = subprocess.run ) -> NativePostRebootReconcilerResult: @@ -387,7 +350,10 @@ def reconcile_external_deletion_if_needed( # evidence or an existing (even dangling) manifest still needs validation. if ( not os.path.lexists(user_root / "authority.json") - and _retains_only_no_change_enrollments(MUTATION_ROOT) + and ( + not any(MUTATION_ROOT.iterdir()) + or t2_mutation_registry.retains_only_no_change_enrollments(MUTATION_ROOT) + ) and not any(CATACOMB_ROOT.iterdir()) and not any(user_root.glob("*.jsonl")) ): diff --git a/tests/test_enrollment_reconciliation.py b/tests/test_enrollment_reconciliation.py index 2d15035..f5f2212 100644 --- a/tests/test_enrollment_reconciliation.py +++ b/tests/test_enrollment_reconciliation.py @@ -1134,6 +1134,7 @@ def test_lost_first_identity_reconciles_as_no_change_after_cold_restart(self): before = enrollment_journal.read(path) self.assertIs(before.phase, enrollment_journal.EnrollmentPhase.OUTCOME_UNKNOWN) self.assertIsNotNone(before.terminal_identity_uuid) + self.assertFalse(enrollment_journal.is_no_change_history(before)) host, live = self.cold_bootstrap_snapshots(value) result = reconciliation.append_reconciled( path, @@ -1145,6 +1146,9 @@ def test_lost_first_identity_reconciles_as_no_change_after_cold_restart(self): records = mutation_journal.read(path) self.assertEqual(result.phase, enrollment_journal.EnrollmentPhase.RECONCILED) self.assertIsNone(result.terminal_identity_uuid) + # The closed journal is retained initial-state evidence for every + # pre-first-enrollment check and candidate selector. + self.assertTrue(enrollment_journal.is_no_change_history(result)) self.assertEqual( records[-1]["milestone"], "E3_RECOVERY_NO_CHANGE_RECONCILED" ) diff --git a/tests/test_mutation_registry.py b/tests/test_mutation_registry.py index fc001ac..7676cc7 100644 --- a/tests/test_mutation_registry.py +++ b/tests/test_mutation_registry.py @@ -35,6 +35,34 @@ def test_baseline_only_enrollment_has_no_mutating_intent(self): self.assertEqual(entry.phase, "baseline-reconciled") self.assertFalse(entry.blocks_new_mutation) + def test_retains_only_no_change_enrollments(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + root.chmod(0o700) + self.assertTrue(registry.retains_only_no_change_enrollments(root)) + mutation.create( + root / "00000000-0000-0000-0000-000000000070.jsonl", + "enroll", + baseline(), + operation_id="00000000-0000-0000-0000-000000000070", + ) + self.assertTrue(registry.retains_only_no_change_enrollments(root)) + rename_path = root / "00000000-0000-0000-0000-000000000071.jsonl" + operation_id, _record = mutation.create( + rename_path, + "rename", + baseline(), + operation_id="00000000-0000-0000-0000-000000000071", + ) + self.assertFalse(registry.retains_only_no_change_enrollments(root)) + rename_path.unlink() + self.assertTrue(registry.retains_only_no_change_enrollments(root)) + (root / "retained.jsonl").touch() + self.assertFalse(registry.retains_only_no_change_enrollments(root)) + (root / "retained.jsonl").unlink() + root.chmod(0o755) + self.assertFalse(registry.retains_only_no_change_enrollments(root)) + def test_routes_completed_enrollment_and_pending_rename_without_ids(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) diff --git a/tests/test_native_enrollment_authority.py b/tests/test_native_enrollment_authority.py index 3d8d9fc..8a5ed6e 100644 --- a/tests/test_native_enrollment_authority.py +++ b/tests/test_native_enrollment_authority.py @@ -30,6 +30,101 @@ def identifier(number: int) -> str: class NativeEnrollmentAuthorityTests(unittest.TestCase): + def test_post_reboot_candidate_skips_retained_no_change_journals(self) -> None: + journal = native_enroll.t2_enrollment_journal + mapping_set = SimpleNamespace(generation="gen") + selected = SimpleNamespace( + linux_uid=1000, apple_uid=501, account_uuid="acct", bag_uuid="bag" + ) + baseline = { + "baseline_version": 2, + "caller_linux_uid": 1000, + "target_linux_uid": 1000, + "apple_uid": 501, + "account_uuid": "acct", + "bag_uuid": "bag", + "mapping_generation": "gen", + } + histories = { + "a.jsonl": SimpleNamespace( + phase=journal.EnrollmentPhase.RECONCILED, + terminal_identity_uuid=None, + baseline=baseline, + ), + "b.jsonl": SimpleNamespace( + phase=journal.EnrollmentPhase.RECONCILED, + terminal_identity_uuid=identifier(7), + baseline=baseline, + ), + } + with tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + for name in histories: + (root / name).touch() + with ( + mock.patch.object(native_enroll, "MUTATION_ROOT", root), + mock.patch.object( + journal, "read", side_effect=lambda path: histories[path.name] + ), + ): + path, history = native_enroll._pending_post_reboot_journal( + mapping_set, selected + ) + self.assertEqual(path.name, "b.jsonl") + self.assertIs(history, histories["b.jsonl"]) + histories["a.jsonl"].terminal_identity_uuid = identifier(3) + with self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, "exactly one reconciled" + ): + native_enroll._pending_post_reboot_journal(mapping_set, selected) + + def test_fresh_enrollment_state_keeps_only_no_change_journals(self) -> None: + cases = { + "empty": ((), (), (), None, False), + "no-change-journal": ((), ("a.jsonl",), (), True, False), + "other-journal": ((), ("a.jsonl",), (), False, True), + "catacomb-bytes": (("prepare",), ("a.jsonl",), (), None, True), + "activation": ((), (), ("x",), None, True), + } + for name, (catacomb, mutations, activation, verdict, rejects) in cases.items(): + with self.subTest(case=name), tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + roots = { + "CATACOMB_ROOT": root / "catacomb", + "MUTATION_ROOT": root / "mutations", + "ACTIVATION_ROOT": root / "activation", + } + for path in roots.values(): + path.mkdir() + for entry in catacomb: + (roots["CATACOMB_ROOT"] / entry).mkdir() + for entry in mutations: + (roots["MUTATION_ROOT"] / entry).touch() + for entry in activation: + (roots["ACTIVATION_ROOT"] / entry).touch() + retains = mock.Mock(return_value=verdict) + with ( + mock.patch.object(native_enroll, "STATE_ROOT", root), + mock.patch.multiple(native_enroll, **roots), + mock.patch.object(native_enroll, "_private"), + mock.patch.object( + native_enroll.t2_mutation_registry, + "retains_only_no_change_enrollments", + retains, + ), + ): + if rejects: + with self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, "not empty" + ): + native_enroll._require_fresh_enrollment_state() + else: + native_enroll._require_fresh_enrollment_state() + if verdict is None: + retains.assert_not_called() + else: + retains.assert_called_once_with(roots["MUTATION_ROOT"]) + def test_native_addition_uses_high_water_candidate_from_exact_inventory(self) -> None: selected = SimpleNamespace(apple_uid=501) store = mock.Mock() From ecb152ac08115d473dbaa4ba509b6470d9636307 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 16:26:02 +0000 Subject: [PATCH 5/7] Show the client-side reason on the stopped enrollment screen When the enrollment or verification task raised EnrollmentUIError or OSError, the TUI set the stopped state and dropped the message, so an EnrollStart rejection looked exactly like a sensor-side stop. Keep a bounded, printable-ASCII copy of the message as the terminal detail and repeat it on stderr after the screen closes. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh5eb1bKqSt7Ec1CdVV --- CHANGELOG.md | 7 +++++++ src/t2-fprintd-enroll-tui.py | 28 +++++++++++++++++++++++++--- tests/test_fprintd_enroll_tui.py | 29 +++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27d03f5..91cf6da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,13 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- Show why the desktop enrollment or verification screen stopped when the + failure happened on the client side, such as an `EnrollStart` D-Bus error, + and repeat that reason on stderr after the screen closes. fprintd's D-Bus + error texts are fixed and identifier-free; only printable ASCII is kept and + the text is bounded. Previously such a failure showed only "Enrollment + stopped · No fingerprint was saved." with no way to tell it apart from a + sensor-side stop. - Report the messages of the project's own exception chain in the enrollment worker's `enrollment stopped` line as a JSON `detail=` list, alongside the existing class and reason fields. Only messages raised by `t2_*` modules are diff --git a/src/t2-fprintd-enroll-tui.py b/src/t2-fprintd-enroll-tui.py index 562efcd..17786e8 100644 --- a/src/t2-fprintd-enroll-tui.py +++ b/src/t2-fprintd-enroll-tui.py @@ -821,6 +821,16 @@ async def run(self) -> int: return self.operation_result or 1 +def _public_error_detail(error: BaseException) -> str: + """Keep only printable ASCII from a client-side failure, bounded in length.""" + text = "".join( + character + for character in str(error)[:160] + if character.isascii() and character.isprintable() + ) + return text or type(error).__name__ + + async def _present_until_closed( ui: EnrollmentUI, stop: asyncio.Event ) -> int: @@ -839,8 +849,15 @@ async def _present_until_closed( return 130 try: result = await operation - except (EnrollmentUIError, OSError): - ui.terminal = "ENROLLMENT STOPPED" + except (EnrollmentUIError, OSError) as error: + ui.terminal = ( + "VERIFICATION STOPPED" + if ui.operation == "verify" + else "ENROLLMENT STOPPED" + ) + # fprintd's D-Bus errors carry fixed, identifier-free messages; + # without them the screen cannot say why nothing was saved. + ui.terminal_detail = _public_error_detail(error) ui.render(bell=True) result = 1 if sys.stdout.isatty() and not stop.is_set(): @@ -934,7 +951,12 @@ def main() -> int: ), expect_no_match=args.expect_no_match, ) - return asyncio.run(_preview_async(ui) if args.preview else _main_async(ui)) + result = asyncio.run(_preview_async(ui) if args.preview else _main_async(ui)) + if result not in (0, 130) and ui.terminal_detail: + # Repeat the stopped reason after the screen is closed so a captured + # terminal session keeps it; it is already identifier-free. + print(f"t2-fprintd-enroll-tui: {ui.terminal_detail}", file=sys.stderr) + return result if __name__ == "__main__": diff --git a/tests/test_fprintd_enroll_tui.py b/tests/test_fprintd_enroll_tui.py index 748ae5c..dc0b496 100644 --- a/tests/test_fprintd_enroll_tui.py +++ b/tests/test_fprintd_enroll_tui.py @@ -123,6 +123,35 @@ def test_taller_windows_preserve_fingerprint_geometry_and_prompt_space(self): self.assertIn("38%", screen) self.assertIn(ui._reference_view()[0], screen) + async def test_client_failure_is_shown_on_the_stopped_screen(self): + class FailingUI(CompletedUI): + operation = "enroll" + terminal = None + terminal_detail = None + + async def run(self) -> int: + self.completed.set() + raise MODULE.EnrollmentUIError( + "fprintd EnrollStart failed: native first-enrollment state " + "is not empty; reconcile retained state\x1b[2J\u00e9" + ) + + ui = FailingUI() + stop = asyncio.Event() + stop.set() + with mock.patch.object(MODULE.sys.stdout, "isatty", return_value=False): + self.assertEqual(await MODULE._present_until_closed(ui, stop), 1) + self.assertEqual(ui.terminal, "ENROLLMENT STOPPED") + self.assertEqual( + ui.terminal_detail, + "fprintd EnrollStart failed: native first-enrollment state " + "is not empty; reconcile retained state[2J", + ) + self.assertEqual( + MODULE._public_error_detail(OSError("")), "OSError" + ) + self.assertEqual(len(MODULE._public_error_detail(OSError("x" * 500))), 160) + async def test_terminal_result_remains_present_until_window_closes(self): ui = CompletedUI() stop = asyncio.Event() From a1f2d813d572f825670a74f1506c3418e26b4f6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 16:48:28 +0000 Subject: [PATCH 6/7] Keep resolved activation journals out of the fresh-state rejection _require_fresh_enrollment_state also demanded an empty activation directory. Every enrollment writes a keybag activation journal there and only t2-native-match prunes it, so the failed first enrollment's own resolved activation record blocked the next first enrollment with "native first-enrollment state is not empty" even after the mutation journal was reconciled. Add t2_activation_journal_retention.retains_only_resolved, true only when every entry is a private activation journal in a phase the pruner already treats as resolved, and let the fresh-state check accept that directory state. Unresolved, blocked, quarantined, malformed or foreign entries still reject. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh5eb1bKqSt7Ec1CdVV --- CHANGELOG.md | 4 +++- docs/TROUBLESHOOTING.md | 8 ++++--- src/t2-native-enroll.py | 15 ++++++++++-- src/t2_activation_journal_retention.py | 22 ++++++++++++++++++ tests/test_activation_journal_retention.py | 27 ++++++++++++++++++++++ tests/test_native_enrollment_authority.py | 13 ++++++++++- 6 files changed, 82 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91cf6da..a72e674 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,9 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). enrollment journals that are complete and proved no SEP change (baseline, aborted before start, or reconciled without an identity) now count as the initial state in those checks and in the post-reboot and authority - publication candidate selectors. Any other journal kind, an unfinished or + publication candidate selectors, as do keybag activation journals that + reached a resolved phase (the failed enrollment's own activation record + otherwise blocked every later first enrollment the same way). Any other journal kind, an unfinished or post-reboot-pending entry, Catacomb bytes, per-user history or an authority manifest still go through reconciliation. - Let `recover-outcome` close a first enrollment whose master Catacomb save diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index d0bf43b..41e9ee8 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -400,9 +400,11 @@ first enrollment never published the per-user authority, needing external-deletion reconciliation, a child command that cannot run without the authority, so fprintd failed its dependency at every start with `reason: null`. fprintd's first-enrollment bootstrap and the enrollment worker -likewise required an empty mutation directory, so `t2-touchid-enroll` ended at -"Enrollment stopped" with no reason. Those checks now recognise a complete -no-change enrollment journal as part of the initial state. +likewise required empty mutation and activation directories, so +`t2-touchid-enroll` ended at "Enrollment stopped" with no reason (the failed +attempt's resolved keybag activation journal was enough). Those checks now +recognise a complete no-change enrollment journal and resolved activation +journals as part of the initial state. ## Deletion failed and enrollment is now blocked diff --git a/src/t2-native-enroll.py b/src/t2-native-enroll.py index 0fb6345..d2ec21b 100755 --- a/src/t2-native-enroll.py +++ b/src/t2-native-enroll.py @@ -61,6 +61,7 @@ import t2_mesa_enrollment_preparation import t2_native_state_restore import t2_mutation_journal +import t2_activation_journal_retention import t2_mutation_registry import t2_native_caller_authorization import t2_native_mutation_authority @@ -332,13 +333,23 @@ def _require_fresh_enrollment_state() -> None: if not any(True for _entry in entries): continue # Enrollment journals that completed without changing the SEP identity - # set (for example one closed by recover-outcome) are retained evidence - # of the initial state, not state awaiting reconciliation. + # set (for example one closed by recover-outcome) and keybag activation + # journals that reached a resolved phase are retained evidence of the + # initial state, not state awaiting reconciliation. if ( path == MUTATION_ROOT and t2_mutation_registry.retains_only_no_change_enrollments(path) ): continue + if path == ACTIVATION_ROOT: + try: + resolved = t2_activation_journal_retention.retains_only_resolved( + path + ) + except t2_activation_journal_retention.ActivationJournalRetentionError: + resolved = False + if resolved: + continue raise NativeEnrollmentError( "native first-enrollment state is not empty; reconcile retained state" ) diff --git a/src/t2_activation_journal_retention.py b/src/t2_activation_journal_retention.py index d4d891e..4b8cda4 100644 --- a/src/t2_activation_journal_retention.py +++ b/src/t2_activation_journal_retention.py @@ -83,6 +83,28 @@ def _is_proved_terminal(path: Path) -> bool: return history.phase in DELETABLE_PHASES +def retains_only_resolved(root: Path = DEFAULT_ROOT) -> bool: + """True when every entry is a private activation journal in a resolved phase. + + Such journals are the retained record of keybag activations that already + reached ready, stopped, or a recovered phase; the pre-first-enrollment + checks may keep them. Anything else, including an entry that is not a + private journal, still requires attention. + """ + _private_directory(root) + try: + names = os.listdir(root) + except OSError as error: + raise ActivationJournalRetentionError( + "activation journal directory is unreadable" + ) from error + return all( + _private_journal(root / name) is not None + and _is_proved_terminal(root / name) + for name in names + ) + + def prune( root: Path = DEFAULT_ROOT, *, diff --git a/tests/test_activation_journal_retention.py b/tests/test_activation_journal_retention.py index e9a5800..aba9c0d 100644 --- a/tests/test_activation_journal_retention.py +++ b/tests/test_activation_journal_retention.py @@ -293,6 +293,33 @@ def test_prune_bounds_growth_by_count_and_age(self): self.assertLessEqual(len(list(self.root.glob("*.jsonl"))), 64) self.assertFalse(stale.exists()) + def test_retains_only_resolved_accepts_terminal_journals_only(self): + self.assertTrue(retention.retains_only_resolved(self.root)) + ready = self._ready_journal(self._path(1)) + self.assertTrue(retention.retains_only_resolved(self.root)) + pending = self._path(2) + self._create(pending, readiness.AliasEvidence(False, None, None, None, None)) + self._append( + pending, + "USER_KEYBAG_LOAD_INTENT", + { + "runtime_generation": self.runtime, + "keybag_sha256": "b" * 64, + "mutation_possible": True, + }, + ) + os.chmod(pending, 0o600) + self.assertFalse(retention.retains_only_resolved(self.root)) + pending.unlink() + self.assertTrue(retention.retains_only_resolved(self.root)) + stray = self.root / "notes.txt" + stray.write_text("x") + os.chmod(stray, 0o600) + self.assertFalse(retention.retains_only_resolved(self.root)) + stray.unlink() + os.chmod(ready, 0o644) + self.assertFalse(retention.retains_only_resolved(self.root)) + def test_prune_keeps_recent_in_progress_journals(self): for index in range(1, 71): path = self._path(index) diff --git a/tests/test_native_enrollment_authority.py b/tests/test_native_enrollment_authority.py index 8a5ed6e..c5c0f82 100644 --- a/tests/test_native_enrollment_authority.py +++ b/tests/test_native_enrollment_authority.py @@ -84,7 +84,8 @@ def test_fresh_enrollment_state_keeps_only_no_change_journals(self) -> None: "no-change-journal": ((), ("a.jsonl",), (), True, False), "other-journal": ((), ("a.jsonl",), (), False, True), "catacomb-bytes": (("prepare",), ("a.jsonl",), (), None, True), - "activation": ((), (), ("x",), None, True), + "activation-resolved": ((), (), ("x",), None, False), + "activation-pending": ((), (), ("x",), None, True), } for name, (catacomb, mutations, activation, verdict, rejects) in cases.items(): with self.subTest(case=name), tempfile.TemporaryDirectory() as temporary: @@ -103,6 +104,7 @@ def test_fresh_enrollment_state_keeps_only_no_change_journals(self) -> None: for entry in activation: (roots["ACTIVATION_ROOT"] / entry).touch() retains = mock.Mock(return_value=verdict) + resolved = mock.Mock(return_value=name == "activation-resolved") with ( mock.patch.object(native_enroll, "STATE_ROOT", root), mock.patch.multiple(native_enroll, **roots), @@ -112,6 +114,11 @@ def test_fresh_enrollment_state_keeps_only_no_change_journals(self) -> None: "retains_only_no_change_enrollments", retains, ), + mock.patch.object( + native_enroll.t2_activation_journal_retention, + "retains_only_resolved", + resolved, + ), ): if rejects: with self.assertRaisesRegex( @@ -124,6 +131,10 @@ def test_fresh_enrollment_state_keeps_only_no_change_journals(self) -> None: retains.assert_not_called() else: retains.assert_called_once_with(roots["MUTATION_ROOT"]) + if activation: + resolved.assert_called_once_with(roots["ACTIVATION_ROOT"]) + else: + resolved.assert_not_called() def test_native_addition_uses_high_water_candidate_from_exact_inventory(self) -> None: selected = SimpleNamespace(apple_uid=501) From 654e1f45e0dcc5049e4cfe46b03186cfec5216d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Mu=C3=B1oz?= <233536261+pablo-ur-fixer@users.noreply.github.com> Date: Sat, 31 Oct 2026 17:35:19 +0000 Subject: [PATCH 7/7] Open t2-touchid-verify on the project's screen from a terminal The stock fprintd-verify client prints "Verify started!" and then waits silently, so a first-time user does not know a touch is expected. The enrollment screen already has a verification mode that says when to touch and shows the result; let the launcher select it with `verify` and exec it from t2-touchid-verify when stdout is a terminal. Without a terminal or without the screen installed the stock client still runs, so scripts keep its exit status and output. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013Z5eh5T2UPSQnihyoB12TP --- CHANGELOG.md | 5 +++++ docs/COMMAND_RECONCILIATION.md | 2 +- src/t2-fprintd-enroll-tui-launch.sh | 12 +++++++++-- src/t2_touchid_cli.py | 4 ++++ tests/test_t2touch_cli.py | 33 +++++++++++++++++++++++++++++ 5 files changed, 53 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a72e674..b083ec7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,11 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- Open `t2-touchid-verify` on the project's own screen when it runs from a + terminal, so it says when to touch the sensor and reports the match or + non-match in the same layout as enrollment. The stock `fprintd-verify` + client printed only "Verify started!" and waited silently. Without a + terminal, or without the screen installed, the stock client still runs. - Show why the desktop enrollment or verification screen stopped when the failure happened on the client side, such as an `EnrollStart` D-Bus error, and repeat that reason on stderr after the screen closes. fprintd's D-Bus diff --git a/docs/COMMAND_RECONCILIATION.md b/docs/COMMAND_RECONCILIATION.md index fd6fdcd..3fc58b4 100644 --- a/docs/COMMAND_RECONCILIATION.md +++ b/docs/COMMAND_RECONCILIATION.md @@ -15,7 +15,7 @@ After first installation, log out and sign back in before enrolling. | `t2-touchid-status [--json]` | Show service availability and your redacted fingerprint inventory. | | `t2-touchid-list [--json]` | List the same validated inventory. | | `t2-touchid-count` | Print the number of enrolled fingerprints. | -| `t2-touchid-verify` | Test an enrolled fingerprint through fprintd. | +| `t2-touchid-verify` | Test an enrolled fingerprint through fprintd, on the same screen as enrollment when run from a terminal. | | `t2-touchid-delete N` | Obtain fresh PolicyKit authorization, then delete one fingerprint. | | `t2-touchid-purge [--yes] [--resume]` | Confirm and authorize journaled deletion of the full inventory, or resume that operation. | diff --git a/src/t2-fprintd-enroll-tui-launch.sh b/src/t2-fprintd-enroll-tui-launch.sh index e63c9a4..f16cb27 100644 --- a/src/t2-fprintd-enroll-tui-launch.sh +++ b/src/t2-fprintd-enroll-tui-launch.sh @@ -2,8 +2,16 @@ # SPDX-License-Identifier: GPL-2.0-only set -euo pipefail -finger=${1:-finger-1} +# `verify` opens the same screen in verification mode; anything else is the +# neutral finger handle to enroll. +mode=${1:-finger-1} + +if [[ $mode == verify ]]; then + exec /opt/t2-touchid/.venv/bin/python \ + /opt/t2-touchid/src/t2-fprintd-enroll-tui.py \ + --verify +fi exec /opt/t2-touchid/.venv/bin/python \ /opt/t2-touchid/src/t2-fprintd-enroll-tui.py \ - --finger "$finger" + --finger "$mode" diff --git a/src/t2_touchid_cli.py b/src/t2_touchid_cli.py index 50c5a4c..05963e6 100644 --- a/src/t2_touchid_cli.py +++ b/src/t2_touchid_cli.py @@ -193,6 +193,10 @@ def verify(user: str) -> int: require_current_user(user) if not service_ready(): raise T2TouchError("Touch ID is not ready; run sudo t2-touchid-doctor") + if ENROLL.is_file() and sys.stdout.isatty(): + # The project's own screen says when to touch; the stock client only + # prints "Verify started!" and waits silently. + os.execv(str(ENROLL), [str(ENROLL), "verify"]) return subprocess.run( ["/usr/bin/fprintd-verify", "-f", "any", user], check=False, diff --git a/tests/test_t2touch_cli.py b/tests/test_t2touch_cli.py index 3944574..21b0c89 100644 --- a/tests/test_t2touch_cli.py +++ b/tests/test_t2touch_cli.py @@ -45,6 +45,39 @@ def test_canonical_and_compatibility_enroll_share_exact_unprivileged_launcher(se self.assertEqual(t2touch.main([], command="enroll"), 1) execute.assert_not_called() + def test_verify_opens_the_project_screen_on_a_terminal(self): + with ( + mock.patch.object(t2touch, "configured_user", return_value="mapped"), + mock.patch.object(t2touch, "require_current_user"), + mock.patch.object(t2touch, "service_ready", return_value=True), + mock.patch.object(Path, "is_file", return_value=True), + mock.patch.object(t2touch.sys.stdout, "isatty", return_value=True), + mock.patch.object(t2touch.os, "execv", side_effect=RuntimeError("exec")) as execute, + self.assertRaisesRegex(RuntimeError, "exec"), + ): + t2touch.main([], command="verify") + execute.assert_called_once_with(str(t2touch.ENROLL), [str(t2touch.ENROLL), "verify"]) + # Without a terminal (or without the screen installed) the stock + # client still runs, so scripts keep its exit status and output. + for installed, tty in ((True, False), (False, True)): + with ( + self.subTest(installed=installed, tty=tty), + mock.patch.object(t2touch, "configured_user", return_value="mapped"), + mock.patch.object(t2touch, "require_current_user"), + mock.patch.object(t2touch, "service_ready", return_value=True), + mock.patch.object(Path, "is_file", return_value=installed), + mock.patch.object(t2touch.sys.stdout, "isatty", return_value=tty), + mock.patch.object(t2touch.os, "execv") as execute, + mock.patch.object( + t2touch.subprocess, "run", return_value=mock.Mock(returncode=3) + ) as run, + ): + self.assertEqual(t2touch.main([], command="verify"), 3) + execute.assert_not_called() + run.assert_called_once_with( + ["/usr/bin/fprintd-verify", "-f", "any", "mapped"], check=False + ) + def test_root_only_configuration_uses_the_calling_account(self): with ( mock.patch.object(Path, "read_text", side_effect=PermissionError),