feat(lab): add isolated iPhone capture evidence

2026-07-16 19:43:41 +03:00
parent 63dd8c8790
commit 19ab973110
11 changed files with 2428 additions and 0 deletions
@@ -0,0 +1,69 @@
+# iPhone / LixelGO capture lab
+
+This is an isolated evidence tool for the XGRIDS K1 plugin. It is not a Mission
+Core runtime dependency and must not be bundled without a separate GPL license
+review.
+
+## Install without Xcode
+
+From the repository root:
+
+```bash
+uv sync --project plugins/xgrids-k1/lab/iphone-capture --frozen
+```
+
+The environment is created under the lab directory. It pins
+`pymobiledevice3==9.36.0`; it does not modify the system Python, Homebrew, the
+Mission Core `.venv`, or the root lockfile.
+
+## USB preflight
+
+Connect exactly one iPhone with a data-capable USB cable, unlock it, confirm the
+Mac accessory prompt, and tap **Trust This Computer** on the iPhone. Then run:
+
+```bash
+uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
+  python plugins/xgrids-k1/lab/iphone-capture/preflight.py
+```
+
+The preflight prints only a device count. It never prints or stores the iPhone
+UDID or serial number.
+
+## Bounded network capture
+
+Run this only after the post-refactor exact-profile K1 regression in ADR 0004:
+
+```bash
+uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
+  python plugins/xgrids-k1/lab/iphone-capture/capture.py \
+  --duration 120
+```
+
+The capture uses the iPhone `pcapd` service over USB, suppresses packet hex on
+stdout, and writes private artifacts under ignored
+`sessions/iphone-k1-observation/`. It is intentionally bounded to 5–600 seconds.
+Each successful run retains the original metadata-bearing `PCAPNG` and creates a
+classic Ethernet `PCAP` that the macOS bundled `tcpdump` can read. The redacted
+manifest records the validated packet count and hashes both artifacts.
+The default refuses a dirty repository; `--allow-dirty` records a source-tree
+fingerprint when an explicitly approved lab run cannot wait for a commit.
+
+Operator events may be recorded while the capture is active and can finish
+after the bounded network process exits. Preserve the original capture manifest
+and create a separate integrity inventory after the operator timeline is closed:
+
+```bash
+uv run python plugins/xgrids-k1/lab/iphone-capture/session_integrity.py \
+  sessions/iphone-k1-observation/<session>
+```
+
+The sealer re-hashes every manifest artifact, adds the manifest and optional
+`operator-events.private.jsonl`, and writes an ignored mode-`0600`
+`integrity.private.json`. It never edits the original manifest or raw capture.
+
+Do not add `--bluetooth` unless Apple's Bluetooth diagnostic logging profile is
+already installed on the iPhone and the operator explicitly approved that
+configuration change. The script never installs the profile.
+
+Wireshark is optional and is not required to record PCAP/PCAPNG. Full Xcode is
+also not required for this path.