From 86f79623e8634af47fbc3444adfe5101abe06eaa Mon Sep 17 00:00:00 2001 From: xianbin <244479407+watli01@users.noreply.github.com> Date: Tue, 27 Oct 2026 15:32:23 -0400 Subject: [PATCH 1/2] Point native account-drift recovery at t2-native-authority-rebind The account generation includes the passwd database epoch, so a package installation whose sysusers hook adds system users changes it. Linux-native first run then said "explicit disabled rebinding and live reconciliation are required", naming the user-map rebind-disabled and enable-reconciled path. That path republishes users.json, while the native provisioning and activation journals pin its generation, so following it leaves first run failing with "protected Linux-native replacement authority does not reconcile", and t2-native-authority-rebind then refuses because the mapping already carries the current generation. Name t2-native-authority-rebind in the first-run error instead. It keeps the mapping and its history intact and records the prior account generation as an alias. Document the native procedure, the warning against the user-map path, and the current limit: one rebind record covers one account change. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 +++++ README.md | 9 +++-- docs/TROUBLESHOOTING.md | 41 +++++++++++++++++++++++ src/README.md | 6 ++++ src/t2-native-enroll.py | 8 +++-- tests/test_native_enrollment_authority.py | 38 +++++++++++++++++++++ 6 files changed, 106 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e546c6..7d45634 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ 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, the warning, and its single-change limit in troubleshooting. + ## 0.1.0 - 2026-09-19 This release brings everyday Touch ID commands into one family, makes desktop diff --git a/README.md b/README.md index a567c35..54fb31a 100644 --- a/README.md +++ b/README.md @@ -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 and the current single-change limit. ## Uninstall diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 99c99a1..f511886 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -100,6 +100,47 @@ 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. + +The rebind record covers one account change. A later rewrite of the passwd +database leaves it stale: account collection then fails with “native account +migration binding is invalid”, and the rebind refuses because a record already +exists. That case has no supported recovery yet. + ## fprintd dependency failure after a cold bridgeOS boot Recovery could not restore the reference machine's saved fingerprints after a diff --git a/src/README.md b/src/README.md index 3452eaf..0c0e7a5 100644 --- a/src/README.md +++ b/src/README.md @@ -1282,6 +1282,12 @@ 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. One record covers one change; a later passwd rewrite +leaves it stale and is not yet handled. `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 diff --git a/src/t2-native-enroll.py b/src/t2-native-enroll.py index e45a8ba..c8080f6 100755 --- a/src/t2-native-enroll.py +++ b/src/t2-native-enroll.py @@ -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) diff --git a/tests/test_native_enrollment_authority.py b/tests/test_native_enrollment_authority.py index 50a44aa..63bd39e 100644 --- a/tests/test_native_enrollment_authority.py +++ b/tests/test_native_enrollment_authority.py @@ -725,6 +725,44 @@ def test_completed_replacement_activation_is_enrollment_authority(self) -> None: expected_keybag_length=len(keybag), ) + def test_account_generation_change_names_the_native_rebind(self) -> None: + """The user-map rebind republishes the pinned mapping; point at the native one.""" + + keybag = b"native-keybag" + with tempfile.TemporaryDirectory() as directory: + keybag_path = Path(directory) / "user.kb" + keybag_path.write_bytes(keybag) + selected = SimpleNamespace( + keybag_path=str(keybag_path), + keybag_sha256=hashlib.sha256(keybag).hexdigest(), + apple_uid=501, + linux_account_generation="a" * 64, + ) + mappings = mock.Mock() + mappings.resolve.return_value = selected + with ( + mock.patch.object( + native_enroll.t2_user_mapping, "load", return_value=mappings + ), + mock.patch.object( + native_enroll.t2_linux_account, + "collect", + return_value=native_enroll.t2_linux_account.AccountEvidence( + 1000, "b" * 64 + ), + ), + mock.patch.object( + native_enroll, + "_private", + return_value=SimpleNamespace(st_size=len(keybag)), + ), + ): + with self.assertRaisesRegex( + native_enroll.NativeEnrollmentError, + "account generation changed.*t2-native-authority-rebind", + ): + native_enroll._load_provisioned_authority(1000, 501) + def test_terminal_identity_recovery_persists_without_recapture(self) -> None: """Protect D196's stable-readback recovery from enrollment replay.""" From 93d1f9d94a27781a09d3f94375b54fe77bc997e0 Mon Sep 17 00:00:00 2001 From: xianbin <244479407+watli01@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:14:41 -0400 Subject: [PATCH 2/2] Let the native rebind replace its own stale record A native account rebind record covers one account change. After a second passwd rewrite (for example another package adding a system user) resolve() raised because the recorded current generation no longer matched, so every Linux account assertion failed with "native account migration binding is invalid", and publish() refused because a record already existed. There was no supported recovery. Validate the record's structure in one helper. A well-formed record whose current generation no longer matches now grants no alias, so the account reads as changed and first run names the rebind again. publish() replaces such a stale record, but only when its prior and mapping generations still match the validated authority. It writes under a unique temporary name, rechecks the record before the atomic rename, and keeps the protected readback. A record that is still current, malformed, or foreign is refused. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 8 ++- README.md | 2 +- docs/TROUBLESHOOTING.md | 10 +-- src/README.md | 5 +- src/t2_native_account_rebind.py | 96 ++++++++++++++++++++--------- tests/test_native_account_rebind.py | 93 ++++++++++++++++++++++++++-- 6 files changed, 174 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d45634..7287d7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,13 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). 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, the warning, and its single-change limit in troubleshooting. + 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 diff --git a/README.md b/README.md index 54fb31a..53e2269 100644 --- a/README.md +++ b/README.md @@ -272,7 +272,7 @@ only after confirming that the mapped Linux account is still the intended accoun 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 and the current single-change limit. +for the commands. ## Uninstall diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index f511886..ed3ba22 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -136,10 +136,12 @@ 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. -The rebind record covers one account change. A later rewrite of the passwd -database leaves it stale: account collection then fails with “native account -migration binding is invalid”, and the rebind refuses because a record already -exists. That case has no supported recovery yet. +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 diff --git a/src/README.md b/src/README.md index 0c0e7a5..1708668 100644 --- a/src/README.md +++ b/src/README.md @@ -1286,8 +1286,9 @@ 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. One record covers one change; a later passwd rewrite -leaves it stale and is not yet handled. +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 diff --git a/src/t2_native_account_rebind.py b/src/t2_native_account_rebind.py index e903b65..892adb9 100644 --- a/src/t2_native_account_rebind.py +++ b/src/t2_native_account_rebind.py @@ -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 @@ -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", @@ -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" @@ -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") @@ -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") @@ -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, @@ -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) diff --git a/tests/test_native_account_rebind.py b/tests/test_native_account_rebind.py index 89819d4..a527a82 100644 --- a/tests/test_native_account_rebind.py +++ b/tests/test_native_account_rebind.py @@ -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__, @@ -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"