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
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,28 @@ 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_<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

- 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
26 changes: 26 additions & 0 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_<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.

## 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
56 changes: 45 additions & 11 deletions src/t2-native-enroll.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand All @@ -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
Expand Down
14 changes: 14 additions & 0 deletions src/t2_enrollment_journal.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 14 additions & 1 deletion src/t2_enrollment_reconciliation.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading