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

## Unreleased

### Fixed

- Point Linux-native first run's account-generation error at
`t2-native-authority-rebind`. It named the user-map disabled-rebind and live
reconciliation, which republishes `users.json` while the native journals pin
its generation, so following it left first run failing with “protected
Linux-native replacement authority does not reconcile”. Document the native
procedure and the warning in troubleshooting.
- Let `t2-native-authority-rebind` replace its own record after a later account
change. A second passwd rewrite (for example another package adding a system
user) left the record stale, which made every Linux account assertion fail
with “native account migration binding is invalid” and made the rebind refuse
because a record existed. A stale record now grants no alias, and the next
explicit rebind replaces it atomically for the same intact authority.

## 0.1.0 - 2026-09-19

This release brings everyday Touch ID commands into one family, makes desktop
Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,9 +267,12 @@ Upgrades validate Linux account authority, biometric readiness, pending
mutation reconciliation, and fprintd as separate stages. A failed stage stops
installation and prints that unit's bounded status. Earlier stages may already
have completed; the installer does not roll them back. Account-generation
changes are never rebound automatically: use the redacted mapping status named by the installer, then
perform the explicit disabled-rebind and live-reconciliation procedure only
after confirming that the mapped Linux account is still the intended account.
changes are never rebound automatically: use the redacted mapping status named by the installer, then,
only after confirming that the mapped Linux account is still the intended account,
bind a Linux-native authority with `t2-native-authority-rebind`. Other mappings
use the explicit disabled-rebind and live-reconciliation procedure. See
[account generation changes](docs/TROUBLESHOOTING.md#native-first-run-reports-that-the-linux-account-generation-changed)
for the commands.

## Uninstall

Expand Down
43 changes: 43 additions & 0 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,49 @@ If preparation stops before requesting a reboot, resolve the reported failure
and rerun the same command. Its recovery hold and prepared-update proof remain
in place across a retry. Reboot only after preparation reports success.

## Native first run reports that the Linux account generation changed

`t2-native-first-run.service` stops with “selected Linux account generation
changed; confirm the account, then run t2-native-authority-rebind”, and fprintd
then reports a dependency failure. The account generation includes the local
passwd database itself, so any rewrite of `/etc/passwd` or `/etc/shadow`
changes it, for example a package installation whose `systemd-sysusers` hook
adds system users. T2Touch never rebinds automatically.

Confirm that the mapped UID is still the intended account, then bind the
unchanged Linux-native authority to it:

```bash
sudo t2-touchid-user-map status --linux-uid 1000
sudo t2-native-authority-rebind --linux-uid 1000 \
--acknowledge-complete-native-authority-migration
sudo systemctl start t2-native-first-run.service t2-biometric-ready.service \
t2-touchid-post-reboot.service fprintd.service
sudo t2-touchid-doctor
```

`status` should report `account-generation-changed` for an enabled mapping.
The rebind validates the complete protected authority, leaves `users.json` and
its enrollment history untouched, and records the prior account generation as
an alias for the current one. On the same installation nothing was migrated, so
the acknowledgement's complete-authority condition holds as long as
`/var/lib/t2-touchid` is intact.

Do not use `t2-touchid-user-map rebind-disabled` or `enable-reconciled` for a
Linux-native authority. They republish `users.json`, while the native
provisioning and activation journals pin its generation, so first run then
stops with “protected Linux-native replacement authority does not reconcile”
and the native rebind refuses because the mapping already carries the current
generation. There is no command that undoes those writes; preserve the current
`users.json` and the journals before attempting any recovery.

A later rewrite of the passwd database, such as another package adding a system
user, changes the generation again. The existing rebind record then grants no
alias, first run reports the change again, and the same rebind command
replaces the stale record after validating the same intact authority. A record
that is still current, or one that no longer matches the authority, is left
unchanged and refused.

## fprintd dependency failure after a cold bridgeOS boot

Recovery could not restore the reference machine's saved fingerprints after a
Expand Down
7 changes: 7 additions & 0 deletions src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1282,6 +1282,13 @@ It validates the imported E4 authority, derives the current strict local-files
account generation, and publishes a root-private per-UID migration record. The
account collector accepts the prior generation only while that record matches
the exact current account and the complete native authority still validates.
The same command covers an account-generation change on the same installation,
such as a package installation rewriting the passwd database. The user-map
`rebind-disabled` path does not apply to a Linux-native authority: republishing
`users.json` breaks the mapping generation that the native provisioning and
activation journals pin. A later passwd rewrite leaves the record stale: it
then grants no alias, and the next explicit rebind replaces it atomically only
while its prior and mapping generations still match the validated authority.

`t2_current_user_authority.py` removes Apple UID/account UUID/bag UUID values
from the public mapping command line. It reads one exact configured Apple user
Expand Down
8 changes: 6 additions & 2 deletions src/t2-native-enroll.py
Original file line number Diff line number Diff line change
Expand Up @@ -212,9 +212,13 @@ def _load_provisioned_authority(
"protected Linux-native mapping authority does not reconcile"
)
if not account.matches_generation(selected.linux_account_generation):
# The mapping generation is pinned by the native provisioning and
# activation journals, so the user-map rebind (which republishes the
# mapping) cannot restore a Linux-native authority. The native account
# rebind keeps the mapping intact and aliases the prior generation.
raise NativeEnrollmentError(
"selected Linux account generation changed; explicit disabled "
"rebinding and live reconciliation are required"
"selected Linux account generation changed; confirm the account, "
"then run t2-native-authority-rebind"
)

provisioning = t2_aks_provisioning.read(PROVISIONING_JOURNAL)
Expand Down
96 changes: 68 additions & 28 deletions src/t2_native_account_rebind.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
The imported mapping and its enrollment history remain byte-for-byte intact.
This root-owned record makes the prior account generation a compatible alias
only while the complete protected authority still validates for the same UID.
A later account change leaves the record stale: it then grants nothing, and a
new explicit rebind may replace it for the same authority.
"""

from __future__ import annotations
Expand Down Expand Up @@ -301,27 +303,9 @@ def _private_digest(path: Path, maximum: int) -> tuple[str, int]:
os.close(descriptor)


def resolve(
linux_uid: int,
current_generation: str,
*,
state_root: Path = STATE_ROOT,
authority_loader: AuthorityLoader | None = None,
) -> str | None:
"""Return the proven prior generation, or None when no rebind exists."""
def _manifest(path: Path, linux_uid: int) -> tuple[str, str, str]:
"""Return (previous, rebound, mapping) generations of a well-formed record."""

linux_uid = _uid(linux_uid)
current_generation = _sha256(current_generation, "current account generation")
if not isinstance(state_root, Path) or not state_root.is_absolute():
raise NativeAccountRebindError("native authority state root is invalid")
path = state_root / "users" / str(linux_uid) / MANIFEST_NAME
if not os.path.lexists(path):
return None
if os.geteuid() != ROOT_UID:
raise NativeAccountRebindError("native account rebind requires root")
_private_directory(state_root)
_private_directory(state_root / "users")
_private_directory(path.parent)
document = _read(path)
fields = {
"schema_version",
Expand Down Expand Up @@ -355,12 +339,40 @@ def resolve(
or document["origin"] != ORIGIN
or document["operation_id"] != operation_id
or document["linux_uid"] != linux_uid
or rebound != current_generation
or previous == rebound
):
raise NativeAccountRebindError(
"native account rebind does not match the current account"
)
raise NativeAccountRebindError("native account rebind record is invalid")
return previous, rebound, mapping_generation


def resolve(
linux_uid: int,
current_generation: str,
*,
state_root: Path = STATE_ROOT,
authority_loader: AuthorityLoader | None = None,
) -> str | None:
"""Return the proven prior generation, or None when no rebind applies."""

linux_uid = _uid(linux_uid)
current_generation = _sha256(current_generation, "current account generation")
if not isinstance(state_root, Path) or not state_root.is_absolute():
raise NativeAccountRebindError("native authority state root is invalid")
path = state_root / "users" / str(linux_uid) / MANIFEST_NAME
if not os.path.lexists(path):
return None
if os.geteuid() != ROOT_UID:
raise NativeAccountRebindError("native account rebind requires root")
_private_directory(state_root)
_private_directory(state_root / "users")
_private_directory(path.parent)
previous, rebound, mapping_generation = _manifest(path, linux_uid)
# A later passwd rewrite leaves a well-formed record stale. It then grants
# no alias: the account reads as changed again and t2-native-authority-
# rebind can replace the record. It never aliases an account it was not
# made for; malformed or foreign records still fail closed above.
if rebound != current_generation:
return None
authority = _load_authority(linux_uid, state_root, authority_loader)
if (
authority.origin != "linux-native-e4"
Expand Down Expand Up @@ -415,7 +427,12 @@ def publish(
account_collector: AccountCollector | None = None,
authority_loader: AuthorityLoader | None = None,
) -> NativeAccountRebindResult:
"""Publish one explicit rebind after complete native state migration."""
"""Publish one explicit rebind after complete native state migration.

A stale record left by a later account change is replaced, but only for the
same intact authority: its prior generation and mapping generation must
still be the validated authority's.
"""

if os.geteuid() != ROOT_UID:
raise NativeAccountRebindError("native account rebind requires root")
Expand All @@ -431,8 +448,7 @@ def publish(
user_root = state_root / "users" / str(linux_uid)
_private_directory(user_root)
path = user_root / MANIFEST_NAME
if os.path.lexists(path):
raise NativeAccountRebindError("native account rebind already exists")
stale = _manifest(path, linux_uid) if os.path.lexists(path) else None
authority = _load_authority(linux_uid, state_root, authority_loader)
if authority.origin != "linux-native-e4":
raise NativeAccountRebindError("authority is not Linux-native")
Expand All @@ -455,6 +471,14 @@ def publish(
raise NativeAccountRebindError(
"native authority account generation is already current"
)
if stale is not None and stale[1] == current_generation:
raise NativeAccountRebindError("native account rebind already exists")
if stale is not None and (
stale[0] != previous or stale[2] != authority.mapping_set.generation
):
raise NativeAccountRebindError(
"existing native account rebind does not match its complete authority"
)
operation_id = str(uuid.uuid4())
document = {
"schema_version": 1,
Expand All @@ -468,7 +492,23 @@ def publish(
encoded = json.dumps(
document, sort_keys=True, separators=(",", ":"), ensure_ascii=True
).encode("ascii")
_write_exclusive(path, encoded)
if stale is None:
_write_exclusive(path, encoded)
else:
temporary = user_root / f".{MANIFEST_NAME}.{operation_id}"
_write_exclusive(temporary, encoded)
try:
if _manifest(path, linux_uid) != stale:
raise NativeAccountRebindError(
"existing native account rebind changed during replacement"
)
os.replace(temporary, path)
except BaseException:
try:
temporary.unlink()
except OSError:
pass
raise
directory = os.open(user_root, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC)
try:
os.fsync(directory)
Expand Down
93 changes: 89 additions & 4 deletions tests/test_native_account_rebind.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,17 +99,16 @@ def test_publish_preserves_authority_and_resolves_previous_generation(self):
self.previous,
)

def test_rejects_wrong_current_generation_and_changed_authority(self):
def test_stale_record_grants_no_alias_and_changed_authority_fails(self):
self.publish()
with self.assertRaisesRegex(
rebind.NativeAccountRebindError, "current account"
):
self.assertIsNone(
rebind.resolve(
self.uid,
"d" * 64,
state_root=self.state,
authority_loader=self.loader,
)
)
changed = SimpleNamespace(
**{
**self.authority.__dict__,
Expand Down Expand Up @@ -199,6 +198,92 @@ def test_failed_write_removes_its_own_incomplete_manifest(self):
rebind._write_exclusive(path, b"incomplete")
self.assertFalse(path.exists())

def test_later_account_change_replaces_stale_record(self):
self.publish()
path = self.user_root / rebind.MANIFEST_NAME
first = json.loads(path.read_text())
self.current = "d" * 64
result = self.publish()
self.assertEqual(
result.redacted()["state"],
"native-authority-rebound-to-current-account",
)
second = json.loads(path.read_text())
self.assertNotEqual(first["operation_id"], second["operation_id"])
self.assertEqual(second["previous_account_generation"], self.previous)
self.assertEqual(second["current_account_generation"], self.current)
self.assertEqual(path.stat().st_mode & 0o777, 0o600)
self.assertEqual(
sorted(item.name for item in self.user_root.iterdir()),
sorted([rebind.MANIFEST_NAME, "user.kb"]),
)
resolved = [
rebind.resolve(
self.uid,
generation,
state_root=self.state,
authority_loader=self.loader,
)
for generation in (self.current, "b" * 64)
]
self.assertEqual(resolved, [self.previous, None])

def test_current_record_is_not_replaced(self):
self.publish()
path = self.user_root / rebind.MANIFEST_NAME
original = path.read_bytes()
with self.assertRaisesRegex(
rebind.NativeAccountRebindError, "already exists"
):
self.publish()
self.assertEqual(path.read_bytes(), original)

def test_stale_record_for_another_authority_is_not_replaced(self):
self.publish()
path = self.user_root / rebind.MANIFEST_NAME
original = path.read_bytes()
self.current = "d" * 64
self.authority = SimpleNamespace(
**{
**self.authority.__dict__,
"mapping_set": SimpleNamespace(generation="e" * 64),
}
)
with self.assertRaisesRegex(
rebind.NativeAccountRebindError, "does not match its complete authority"
):
self.publish()
self.assertEqual(path.read_bytes(), original)

def test_malformed_existing_record_blocks_publish(self):
path = self.user_root / rebind.MANIFEST_NAME
path.write_text(json.dumps({"schema_version": 1}))
path.chmod(0o600)
with self.assertRaises(rebind.NativeAccountRebindError):
self.publish()
self.assertEqual(json.loads(path.read_text()), {"schema_version": 1})

def test_replacement_aborts_when_record_changes_underneath(self):
self.publish()
path = self.user_root / rebind.MANIFEST_NAME
original = path.read_bytes()
stale = rebind._manifest(path, self.uid)
self.current = "d" * 64
with mock.patch.object(
rebind,
"_manifest",
side_effect=[stale, ("f" * 64, self.current, self.mapping_generation)],
):
with self.assertRaisesRegex(
rebind.NativeAccountRebindError, "changed during replacement"
):
self.publish()
self.assertEqual(path.read_bytes(), original)
self.assertEqual(
sorted(item.name for item in self.user_root.iterdir()),
sorted([rebind.MANIFEST_NAME, "user.kb"]),
)

def test_current_binding_is_rejected(self):
with self.assertRaisesRegex(
rebind.NativeAccountRebindError, "already current"
Expand Down
Loading