[rickmark]

Requested by Rick · project thread

Before: most of what the README promised was stubbed or broken. USBMUX streams got the wrong buffer offset and the plist reassembler never advanced, so no plists were ever decoded. Classic .pcap was opened with the pcapng parser. An unknown pcapng link type sent the parser into an infinite loop. USBPcap captures never applied SET_CONFIGURATION, so their bulk traffic was never routed. Malformed captures crashed on asserts. The DFU and Recovery experts recorded nothing, and the test suite was a single empty test.

After: Darwin, USBPcap and Linux usbmon captures in pcapng or classic pcap are decoded end to end. Lockdown and service plists are decoded per stream, DFU images and recovery uploads are reassembled and can be extracted, and corrupt captures are reported instead of crashing. 34 tests cover all of this using synthetic captures.

How:

• Input: the format is sniffed from the magic number. The parser handles multiple pcapng sections and interfaces and simple packet blocks, adds a classic pcap reader (either byte order, µs/ns), and adds usbmon (189/220). Every structure is bounds-checked and copied with readStruct (no unaligned reinterpret_cast). Bad packets become warnings, and the parser stops cleanly on corrupt framing. The #pragma pack(1) that leaked out of pcapng.h into every later header is now balanced.
• Transfers: DeviceHandle pairs submit and complete events, taking OUT data from the submit and IN data from the completion. Direction comes from bmRequestType. Re-enumeration as a different device (DFU → Recovery → Normal) starts a new device session.
• Device: configurations are keyed by bConfigurationValue, alternate settings and SET_INTERFACE are tracked (the old TODO: Alternates), BOS descriptors are kept (previously always dropped), and strings are decoded to UTF-8. Class and vendor requests are routed by recipient and interface. Output no longer mixes wcout and cout.
• USBMUX / MuxStream: mux packets are reassembled across USB transfers, v1 and v2 headers are both handled, and the TCP data offset, FIN/RST and pre-capture connections are respected. Big-endian length-prefixed XML and binary plists are decoded in both directions. TLS and raw streams are detected, and services are named from lockdownd StartService replies.
• DFU / Recovery: DNLOAD images are reassembled, the DFU state is tracked from GETSTATUS, and anomalies are flagged (oversized DNLOAD, ABORT after a partial download, unknown requests). iBoot commands and responses, 0x41-announced bulk uploads and console output are decoded.
• CLI: new --verbose, --plists, --extract <dir> and --warnings options.
• Build/CI: the code is now a demuxusb_lib static library. New DEMUXUSB_SANITIZE option for ASan/UBSan. The CI matrix covers Ubuntu, Ubuntu with sanitizers and macOS, on both push and pull_request. Tests include mutation fuzzing of every format. The README is updated to match the new API.

Verified locally: GCC Release, GCC Debug with ASan/UBSan, and Clang all build without warnings and pass 34/34 tests. I also ran the CLI and the README example against a generated capture.

The tests use synthetic captures because the repo has no real Apple captures. The Darwin completion layout follows what the previous code assumed, so it's worth running against a real macOS restore capture.

---

Generated by Claude Code