feat: prove and decode K1 realtime MQTT streams

README.md

@@ -4,9 +4,15 @@ Pre-production research project for connecting an owner-controlled
 XGRIDS/LixelKity K1 to a Mac without LixelGO, firmware changes, device opening,
 or speculative writes.
 
-Current status: repository scaffold and implementation plan. No command in the
-repository currently writes to the K1, changes the router, or installs system
-packages.
+Current status: live proof completed on firmware 3.0.2. The Mac provisioned the
+K1 onto an existing LAN without LixelGO, connected to its MQTT broker, captured
+the scan-correlated point-cloud and pose streams, and decoded both successfully.
+
+The repository now contains one narrowly gated state-changing command:
+`ble wifi-configure`. It accepts only the reviewed firmware-3 provisioning
+profile and requires explicit `--confirm-write`; the Wi-Fi password is collected
+through a hidden local macOS dialog. MQTT capture and decoding are read-only.
+Nothing changes router settings, firmware or global Python packages.
 
 ## Available stand
 
@@ -29,9 +35,10 @@ The project has three independent gates:
 3. Without LixelGO, K1 can be associated with Wi-Fi and a proprietary data
    session can be opened.
 
-Only after gate 3 do point-cloud, pose, status, and camera stream decoders become
-meaningful implementation work. Local `map.las` and `poses.csv` prove internal
-capabilities, not an externally accessible network format.
+All three gates are now proven on the tested unit. The external stream is plain
+MQTT 3.1.1 on TCP 1883. Firmware-3 `lio_pcl` is protobuf wrapped in a raw LZ4
+block, and `lio_pose` is an uncompressed protobuf. Raw panoramic camera access is
+still unproven and is not implied by point-cloud success.
 
 ## Local environment
 
@@ -50,19 +57,33 @@ uv run pytest
 and reports external tools; it does not request Bluetooth permission, scan the
 LAN, touch the K1, alter Homebrew, or change capture permissions.
 
-The currently implemented laboratory commands are:
+The implemented laboratory commands include:
 
 ```bash
 uv run k1link ble scan --duration 30 --out sessions/<id>/captures/ble.json
 uv run k1link ble gatt-dump --device <corebluetooth-uuid> \
   --out sessions/<id>/captures/gatt.json
+uv run k1link ble wifi-configure --device <corebluetooth-uuid> \
+  --profile xgrids-k1-fw3-wifi-v1 --write-mode with_response \
+  --confirm-write --out sessions/<id>/captures/wifi.sensitive.json
 uv run k1link net snapshot --out sessions/<id>/captures/network.json
+uv run k1link net mqtt-capture --host <confirmed-private-k1-ip> \
+  --confirm-owned-device --duration 180 \
+  --out sessions/<id>/captures/mqtt-run
+uv run k1link analyze mqtt-streams \
+  --capture sessions/<id>/captures/mqtt-run/mqtt.raw.k1mqtt \
+  --out sessions/<id>/analysis/mqtt-streams.summary.json
 ```
 
-On macOS the scan is active CoreBluetooth discovery, but it does not connect to
-or modify devices. `gatt-dump` connects and performs service discovery only; it
-does not read characteristic values, subscribe to notifications or write
-configuration. Session output is sensitive and ignored by Git.
+On macOS the BLE scan is active CoreBluetooth discovery, but it does not connect
+to or modify devices. `gatt-dump` connects and performs service discovery only.
+`mqtt-capture` accepts only a literal RFC1918 target, uses a fixed report-topic
+allowlist, never publishes and never reconnects. It writes a length-framed raw
+file, JSONL metadata and an integrity summary with mode `0600`.
+
+Session output is sensitive and ignored by Git. It can contain device identity,
+trajectory, mapped interiors and local addressing even when no credentials are
+present.
 
 ## Documentation
 
@@ -70,6 +91,9 @@ configuration. Session output is sensitive and ignored by Git.
 - [Implementation gates](docs/01_IMPLEMENTATION_PLAN.md)
 - [First lab runbook](docs/02_FIRST_LAB_RUNBOOK.md)
 - [Artifact and secret policy](docs/03_ARTIFACT_POLICY.md)
+- [Reviewed BLE Wi-Fi profile](docs/04_K1_WIFI_PROVISIONING_PROFILE.md)
+- [Verified MQTT stream profile](docs/05_K1_MQTT_STREAM_PROFILE.md)
+- [Redacted live lab report](docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md)
 - [Session manifest schema](schemas/session-manifest.schema.json)
 - [Reference input provenance](docs/reference/README.md)
 
@@ -84,10 +108,12 @@ controlled notification listening, autonomous button operation, targeted
 capture of traffic to or from the confirmed K1 address, and offline analysis of
 owned artifacts.
 
-BLE writes, provisioning, application-session packets, active service probes,
-and router configuration changes require evidence and an explicit reviewed
-step. Random writes, fuzzing, brute force, firmware operations, destructive file
-access, and credential guessing are out of scope.
+The reviewed provisioning write requires its named profile and explicit operator
+confirmation. Application command publishing remains disabled: physical
+double-click is the verified start/stop mechanism. Any future MQTT publisher,
+router configuration change or new BLE write requires its own evidence and
+reviewed step. Random writes, fuzzing, brute force, firmware operations,
+destructive file access and credential guessing remain out of scope.
 
 Real captures, projects, router metadata, serials, credentials, maps, images,
 and logs are ignored by normal Git. Redacted manifests and SHA-256 inventories