Skip to content
51 changes: 51 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,57 @@ 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

- 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
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
2 changes: 1 addition & 1 deletion docs/COMMAND_RECONCILIATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

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
12 changes: 10 additions & 2 deletions src/t2-fprintd-enroll-tui-launch.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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"
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
Loading