diff --git a/CHANGELOG.md b/CHANGELOG.md index e8199cc..99438a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +### Added + +- Read-only pre-authority inventory (`t2-touchid-inventory --preclient` and + `bridge-xpc-probe.py --preclient-inventory`). It admits only the exact + successful empty-list sentinel and exact absent-Catacomb metadata, reports + `authority: unknown`, never creates or adopts authority, and fails closed on + other shapes. This lets a pre-enrollment compatibility check run without + weakening the full-inventory guard or duplicating the private parser. + ## 0.1.2 - 2026-10-28 On our test Mac, after T2Touch had run in Linux, macOS removed the account's diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index f2855ec..1cb8043 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -353,6 +353,29 @@ This validates the complete imported Linux-native authority and binds its unchanged history to the current local account. It does not apply to macOS state, which still has no supported end-user migration command. +## Checking state before native first-run + +`t2-touchid-inventory` normally needs a completed native authority and a +present Catacomb. Before native first-run, use the read-only pre-authority +mode: + +```sh +sudo t2-touchid-inventory --preclient --json +``` + +It reports `state: absent-baseline` or `state: present`, with +`authority: unknown` and `mutation_performed: false`. It never creates, +adopts, recovers, or enrolls authority. The absent baseline is admitted only +from the exact successful empty-list sentinel and exact-sized all-zero +Catacomb metadata at status 22; any other shape fails closed. Protocol v2 is +attested by a successful v2-only identity command, not by biometric command 1, +which some T2 firmware rejects with `kIOReturnBadArgument`. + +Use this to answer whether the pre-authority surface is safe to precede native +first-run. It does not replace native first-run, and it does not make a present +Catacomb adoptable. The underlying research probe exposes the same contract as +`bridge-xpc-probe.py --initialize --preclient-inventory`. + ## Fingerprint inventory or enrollment is unavailable An empty inventory is normal before first enrollment and after deleting the diff --git a/src/bridge-xpc-probe.py b/src/bridge-xpc-probe.py index 7ad0ecd..7ec4024 100755 --- a/src/bridge-xpc-probe.py +++ b/src/bridge-xpc-probe.py @@ -1083,6 +1083,239 @@ def summarize_full_inventory( return public, private +def _preclient_status_output(reply: object, name: str) -> tuple[int, object]: + """Return one bounded command status and its opaque output.""" + if type(reply) is not list or len(reply) != 2: + raise ValueError(f"{name} reply is malformed") + status, output = reply + if ( + type(status) is not int + or isinstance(status, bool) + or not -(2**31) <= status < 2**32 + ): + raise ValueError(f"{name} reply status is malformed") + return status, output + + +def _preclient_identity_records( + reply: object, name: str, record_size: int +) -> tuple[bytes, ...]: + """Parse one identity list, admitting only the exact empty sentinel.""" + status, output = _preclient_status_output(reply, name) + if status != 0: + raise ValueError(f"{name} query failed") + if is_biometric_nil_output(output): + return () + if type(output) is not bytes or len(output) % record_size: + raise ValueError(f"{name} records are malformed") + return tuple( + output[offset : offset + record_size] + for offset in range(0, len(output), record_size) + ) + + +def _preclient_catacomb_metadata(replies: dict) -> tuple[bool, bool]: + """Return (UUID present, component present) for the exact absent baseline.""" + uuid_status, uuid_output = _preclient_status_output( + replies["catacomb_uuid"], "Catacomb UUID" + ) + hash_status, hash_output = _preclient_status_output( + replies["catacomb_hash"], "Catacomb hash" + ) + if (uuid_status, hash_status) == (22, 22): + if ( + type(uuid_output) is not bytes + or len(uuid_output) != 16 + or any(uuid_output) + or type(hash_output) is not bytes + or len(hash_output) != 33 + or any(hash_output) + ): + raise ValueError("absent Catacomb metadata is malformed") + return False, False + if (uuid_status, hash_status) != (0, 0): + raise ValueError("Catacomb metadata status is neither absent nor present") + if ( + type(uuid_output) is not bytes + or len(uuid_output) != 16 + or not any(uuid_output) + or type(hash_output) is not bytes + or len(hash_output) != 33 + ): + raise ValueError("present Catacomb metadata is malformed") + return True, bool(hash_output[0]) + + +def summarize_preclient_inventory( + first: dict, second: dict, macos_user_id: int +) -> dict: + """Validate a read-only pre-authority surface without adopting state. + + The full inventory is a post-install check: it requires protocol v2 and + present Catacomb metadata. Before native first-run the same wire surface + is legitimately empty, so this contract admits only the exact successful + empty-list sentinel and the exact absent-Catacomb metadata. It never + provisions, adopts, recovers, or mutates anything. + """ + if type(first) is not dict or type(second) is not dict: + raise ValueError("pre-authority inventory snapshots are malformed") + if first != second: + raise ValueError("pre-authority inventory changed between collections") + replies = first.get("replies") + events = first.get("events") + if type(replies) is not dict or type(events) is not dict: + raise ValueError("pre-authority inventory snapshots are malformed") + required = { + "protocol", + "global_identities", + "maximum_capacity", + "per_user_identities", + "free_capacity", + "catacomb_uuid", + "catacomb_hash", + "catacomb_state", + "sks_lock_state", + } + if set(replies) != required or set(events) != required: + raise ValueError("pre-authority inventory is incomplete") + if any(type(value) is not list or value for value in events.values()): + raise ValueError("pre-authority inventory emitted an unexpected service event") + + protocol_status, protocol_output = _preclient_status_output( + replies["protocol"], "biometric protocol" + ) + explicit_v2 = ( + protocol_status == 0 + and type(protocol_output) is bytes + and len(protocol_output) == 4 + and struct.unpack(" maximum + or len(per_user_records) > maximum + or len(global_records) > maximum + ): + raise ValueError("identity capacity is inconsistent") + + state_status, state_output = _preclient_status_output( + replies["catacomb_state"], "Catacomb state" + ) + if ( + state_status != 0 + or type(state_output) is not bytes + or len(state_output) not in (8, 16) + ): + raise ValueError("Catacomb state reply is malformed") + try: + states = t2_catacomb_protocol.parse_user_states(state_output) + except t2_catacomb_protocol.CatacombProtocolError as error: + raise ValueError("Catacomb state records are malformed") from error + master = t2_catacomb_protocol.CatacombComponent.master() + selected = t2_catacomb_protocol.CatacombComponent.user(macos_user_id) + master_records = [record for record in states if record.component == master] + selected_records = [record for record in states if record.component == selected] + if len(master_records) != 1: + raise ValueError("Catacomb state has no unique master component") + if len(selected_records) > 1: + raise ValueError("Catacomb state repeats the selected user component") + if per_user_records and not selected_records: + raise ValueError("per-user identities have no Catacomb component") + + sks_status, sks_output = _preclient_status_output( + replies["sks_lock_state"], "SKS lock state" + ) + if ( + sks_status != 0 + or type(sks_output) is not bytes + or len(sks_output) != 4 + ): + raise ValueError("SKS lock state reply is malformed") + + absent_baseline = not uuid_present and not component_present + if absent_baseline: + if per_user_records or global_records: + raise ValueError("absent baseline contains identity records") + if len(states) != 1 or selected_records: + raise ValueError("absent baseline is not the master-only state") + state = "absent-baseline" + else: + state = "present" + + return { + "schema_version": 1, + "mode": "preclient-inventory", + "diagnostic_contract": "pre-authority-v1", + "state": state, + "biometric_protocol_version": 2, + "biometric_protocol_attestation": ( + "command-1" if explicit_v2 else "v2-global-identity-command" + ), + "per_user_identity_count": len(per_user_records), + "global_identity_count": len(global_records), + "maximum_identity_capacity": maximum, + "configured_user_free_capacity": free, + "catacomb_uuid_present": uuid_present, + "catacomb_component_present": component_present, + "catacomb_master_state": master_records[0].state, + "selected_user_component_present": bool(selected_records), + "catacomb_state_word_count": len(state_output) // 4, + "sks_lock_state_raw": struct.unpack(" list[tuple[str, int, bytes]]: @@ -1683,6 +1916,14 @@ def main() -> None: action="store_true", help="collect complete inventory snapshots A and B on one connection", ) + parser.add_argument( + "--preclient-inventory", + action="store_true", + help=( + "collect read-only pre-authority inventory without provisioning " + "or adopting state" + ), + ) parser.add_argument( "--private-inventory-output", metavar="PATH", @@ -1777,6 +2018,28 @@ def main() -> None: parser.error( "named, resolved-name, and resolved-slot matching conflict" ) + if args.preclient_inventory and any( + ( + args.full_inventory, + args.private_inventory_output is not None, + args.match_seconds is not None, + args.authorized_credential_set_match, + args.private_match_events_output is not None, + args.reset_sensor, + args.cancel_operation, + args.load_calibration, + args.load_catacomb_archive is not None, + args.load_native_catacomb_root is not None, + args.load_biolockout_archive is not None, + args.load_biolockout_record is not None, + args.save_biolockout_output is not None, + args.save_biolockout_after_match_output is not None, + ) + ): + parser.error( + "--preclient-inventory is read-only and cannot be combined with " + "mutation, save, or match options" + ) if not 0 <= args.macos_user_id <= 0xFFFFFFFF: parser.error("--macos-user-id must fit an unsigned 32-bit integer") if not args.host or not args.interface: @@ -2080,6 +2343,19 @@ def bind_match_password(external_form: bytes) -> None: client_version = min(api_version, 2) result["bridge_client_version"] = client_version operations.append("read bridge version") + if args.preclient_inventory: + if not args.initialize: + raise ValueError("--preclient-inventory requires --initialize") + first_preclient = collect_full_inventory(sock, args.macos_user_id) + second_preclient = collect_full_inventory(sock, args.macos_user_id) + result.update( + summarize_preclient_inventory( + first_preclient, + second_preclient, + args.macos_user_id, + ) + ) + operations.append("pre-authority inventory snapshots A/B") if args.full_inventory: if not args.initialize: raise ValueError("--full-inventory requires --initialize") diff --git a/src/t2-touchid-inventory.py b/src/t2-touchid-inventory.py index 514eaa6..887f4f7 100755 --- a/src/t2-touchid-inventory.py +++ b/src/t2-touchid-inventory.py @@ -118,9 +118,112 @@ def summarize_probe(probe: Any, expected_uid: int) -> dict[str, Any]: return result +def summarize_preclient_probe(probe: Any) -> dict[str, Any]: + if not isinstance(probe, dict): + raise InventoryError("pre-authority probe returned a non-object result") + if probe.get("schema_version") != 1: + raise InventoryError("pre-authority schema version is not supported") + if probe.get("mode") != "preclient-inventory": + raise InventoryError("probe did not return a pre-authority inventory") + if probe.get("diagnostic_contract") != "pre-authority-v1": + raise InventoryError("pre-authority diagnostic contract is not supported") + if probe.get("mutation_performed") is not False: + raise InventoryError("pre-authority probe reports a mutation") + if probe.get("authority") != "unknown": + raise InventoryError("pre-authority probe claims authority") + if probe.get("identifiers_redacted") is not True: + raise InventoryError("pre-authority probe did not redact identifiers") + if probe.get("double_collection_equal") is not True: + raise InventoryError("pre-authority inventory changed during collection") + state = probe.get("state") + if state not in {"absent-baseline", "present"}: + raise InventoryError("pre-authority state is unknown") + if ( + probe.get("biometric_protocol_version") != 2 + or probe.get("biometric_protocol_attestation") + not in {"command-1", "v2-global-identity-command"} + ): + raise InventoryError("biometric protocol v2 is not attested") + for field in ( + "per_user_identity_count", + "global_identity_count", + "maximum_identity_capacity", + "configured_user_free_capacity", + "catacomb_master_state", + "catacomb_state_word_count", + "sks_lock_state_raw", + ): + value = probe.get(field) + if type(value) is not int or not 0 <= value <= 0xFFFFFFFF: + raise InventoryError(f"pre-authority {field} is invalid") + maximum = probe["maximum_identity_capacity"] + free = probe["configured_user_free_capacity"] + per_user = probe["per_user_identity_count"] + global_count = probe["global_identity_count"] + if free > maximum or per_user > maximum or global_count > maximum: + raise InventoryError("pre-authority identity counts exceed capacity") + for field in ( + "catacomb_uuid_present", + "catacomb_component_present", + "selected_user_component_present", + ): + if type(probe.get(field)) is not bool: + raise InventoryError(f"pre-authority {field} is invalid") + if state == "absent-baseline" and ( + per_user + or global_count + or probe["catacomb_uuid_present"] + or probe["catacomb_component_present"] + or probe["selected_user_component_present"] + ): + raise InventoryError("absent baseline contains live state") + if state == "present" and not ( + per_user + or global_count + or probe["catacomb_uuid_present"] + or probe["catacomb_component_present"] + or probe["selected_user_component_present"] + ): + raise InventoryError("present state has no matching evidence") + return { + "schema_version": 1, + "mode": "preclient-inventory", + "diagnostic_contract": "pre-authority-v1", + "state": state, + "biometric_protocol_version": 2, + "biometric_protocol_attestation": probe[ + "biometric_protocol_attestation" + ], + "per_user_identity_count": per_user, + "global_identity_count": global_count, + "maximum_identity_capacity": maximum, + "configured_user_free_capacity": free, + "catacomb_uuid_present": probe["catacomb_uuid_present"], + "catacomb_component_present": probe["catacomb_component_present"], + "catacomb_master_state": probe["catacomb_master_state"], + "selected_user_component_present": probe[ + "selected_user_component_present" + ], + "catacomb_state_word_count": probe["catacomb_state_word_count"], + "sks_lock_state_raw": probe["sks_lock_state_raw"], + "double_collection_equal": True, + "authority": "unknown", + "mutation_performed": False, + "identifiers_redacted": True, + } + + def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--json", action="store_true", help="emit compact JSON") + parser.add_argument( + "--preclient", + action="store_true", + help=( + "read-only pre-authority inventory; never provisions or adopts " + "authority" + ), + ) args = parser.parse_args() try: config = read_assignments(CONFIG) @@ -138,6 +241,9 @@ def main() -> int: probe = project / "src/bridge-xpc-probe.py" if not python.is_file() or not probe.is_file() or not host or not interface: raise InventoryError("Touch ID installation is incomplete") + probe_mode = ( + "--preclient-inventory" if args.preclient else "--full-inventory" + ) completed = subprocess.run( [ "/usr/bin/flock", @@ -153,7 +259,7 @@ def main() -> int: "--port", port_text, "--macos-user-id", str(uid), "--initialize", - "--full-inventory", + probe_mode, ], check=False, capture_output=True, @@ -164,7 +270,12 @@ def main() -> int: if completed.returncode: detail = completed.stderr.strip().splitlines()[-1:] or ["unknown error"] raise InventoryError(f"BridgeXPC probe failed: {detail[0]}") - result = summarize_probe(json.loads(completed.stdout), uid) + probe_result = json.loads(completed.stdout) + result = ( + summarize_preclient_probe(probe_result) + if args.preclient + else summarize_probe(probe_result, uid) + ) except (OSError, ValueError, json.JSONDecodeError, subprocess.TimeoutExpired, InventoryError) as error: parser.error(str(error)) print(json.dumps(result, separators=(",", ":") if args.json else None, indent=None if args.json else 2, sort_keys=True)) diff --git a/tests/test_bridge_xpc_probe.py b/tests/test_bridge_xpc_probe.py index bb68ba1..bc74a63 100644 --- a/tests/test_bridge_xpc_probe.py +++ b/tests/test_bridge_xpc_probe.py @@ -779,5 +779,136 @@ def test_v2_global_identity_reply_attests_rejected_protocol_query(self): self.assertEqual(private["biometric_protocol_version"], 2) +class PreclientInventoryTests(unittest.TestCase): + COMMANDS = ( + "protocol", + "global_identities", + "maximum_capacity", + "per_user_identities", + "free_capacity", + "catacomb_uuid", + "catacomb_hash", + "catacomb_state", + "sks_lock_state", + ) + + def absent_baseline(self): + return { + "replies": { + "protocol": [-536870206, b"\0" * 4], + "global_identities": [0, wire.BIOMETRIC_NIL_OUTPUT_SENTINEL], + "maximum_capacity": [0, struct.pack("