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
46 changes: 46 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,52 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## Unreleased

### Fixed

- 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, 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
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_<UID>.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

- 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
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
Expand Down
8 changes: 5 additions & 3 deletions docs/FIRST_RUN_RECOVERY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
38 changes: 38 additions & 0 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,44 @@ 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_<UID>.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.

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`. fprintd's first-enrollment bootstrap and the enrollment worker
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

A deletion error can mean SEP removed the fingerprint but local persistence did
Expand Down
35 changes: 34 additions & 1 deletion src/t2-fprint-enrollment-worker.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from __future__ import annotations

import argparse
import json
import os
import sys
from pathlib import Path
Expand All @@ -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 "<empty>")
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",
Expand Down Expand Up @@ -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
Expand Down
28 changes: 25 additions & 3 deletions src/t2-fprintd-enroll-tui.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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():
Expand Down Expand Up @@ -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__":
Expand Down
90 changes: 71 additions & 19 deletions src/t2-native-enroll.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -329,10 +330,29 @@ 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) 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"
)


def _require_private_runtime_root() -> None:
Expand Down Expand Up @@ -1574,6 +1594,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:
Expand Down Expand Up @@ -1630,11 +1652,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:
Expand Down Expand Up @@ -1956,8 +1974,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
Expand Down Expand Up @@ -1989,18 +2007,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"
Expand All @@ -2009,6 +2038,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
Expand Down
22 changes: 22 additions & 0 deletions src/t2_activation_journal_retention.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
*,
Expand Down
Loading