@ecopoesis/homebridge-dmx 0.1.0

package/tools/derive-dmx-key.mjs

@@ -0,0 +1,189 @@
+// Stick-DE3 DMX cipher — per-session AES-256 key derivation (KDF).
+//
+// ════════════════════════════════════════════════════════════════════════
+// RECOVERED 2026-05-21 by pure static RE (Ghidra) of the 2024-03-21 ESA2
+// HardwareManager. This is the LAST blocker for a standalone plugin: it lets
+// the plugin derive its own per-session key without the Hardware Manager.
+//
+// Call chain (ESA2 file addrs):
+//   on_listWidgetDevice_itemSelectionChanged
+//    → FUN_100178030 → FUN_100107650  (the KDF)
+//        ├ vt[0x28] FUN_1001c0a50  opcode 0x10  — query Stick crypto state
+//        ├ FUN_1004032b0           — generate ephemeral P-256 keypair
+//        ├ vt[0x20] FUN_1001c0650  opcode 0x0F  — exchange public keys
+//        ├ vt[0x38] FUN_100180e90  — return hardcoded static point (33B)
+//        ├ FUN_100402ab0           — SEC1 decompress the static point
+//        ├ FUN_1003ff3c0  ×2       — P-256 scalar multiply
+//        └ FUN_1003f5740 / FUN_1003f4530 — install 32B key at cipher+0x48/+0x68
+//
+// THE KDF (FUN_100107650), in full:
+//   1. d   = random scalar mod n            (ephemeral private key)
+//   2. our = d · G                          (our ephemeral public key)
+//   3. send `our`, receive Stick pubkey `Q` (opcode 0x0F handshake)
+//   4. S   = decompress(STATIC_POINT_33B)   (hardcoded, baked into the app)
+//   5. AES-256 key = X(d · S)  XOR  X(d · Q)
+//
+//   It is a TWO-DH construction: one DH against a fixed/pre-shared key `S`
+//   (authenticates the app) and one against the Stick's per-session key `Q`
+//   (gives forward secrecy). The Stick computes the identical key as
+//   X(s·our) XOR X(e·our), where s,e are its static/ephemeral privates —
+//   the two agree by ECDH symmetry.
+//
+// CURVE: NIST P-256 / secp256r1 / prime256v1. Confirmed three ways from the
+// binary: prime p, order n, and base point G all byte-match P-256, and the
+// curve `b` constant 5ac635d8…27d2604b is added during point decompression.
+//
+// ENDIANNESS: the Stick stores/wires every 256-bit coordinate as
+// little-endian limbs (byte 0 = least-significant). Node's `crypto` works in
+// big-endian (SEC1), so we byte-reverse at every boundary. The installed AES
+// key is the little-endian form of  X(d·S) XOR X(d·Q).
+//
+//   ✓ VERIFIED end-to-end (2026-05-21): this derivation reproduces the exact
+//   AES-256 key installed in a real captured session — checked against an
+//   lldb-dumped ephemeral `d` + the Stick pubkey from the handshake pcap.
+//   See tools/verify-kdf.mjs.
+// ════════════════════════════════════════════════════════════════════════
+//
+// Usage:  node tools/derive-dmx-key.mjs            (runs the self-test)
+
+import crypto from 'node:crypto';
+
+// ── P-256 domain parameters (standard; matched against the binary) ──────────
+export const P256 = {
+  p: 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn,
+  n: 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n,
+  a: 0xffffffff00000001000000000000000000000000fffffffffffffffffffffffcn, // -3 mod p
+  b: 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn,
+  Gx: 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296n,
+  Gy: 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5n,
+};
+
+// ── The hardcoded static public point S, recovered from the binary ──────────
+// A 33-byte SEC1-compressed P-256 point stored VERBATIM at file offset
+// 0x7b0490 (vmaddr 0x1007b0490). prefix 0x03 => odd Y. vt[0x38] hands this
+// raw buffer straight to the SEC1 decompressor. (An earlier RE pass XOR-masked
+// these bytes with 0x51,0x52,… — that produced a different value used
+// elsewhere in the app; it is NOT the KDF static point. The raw bytes below
+// are the ones that reproduce a real session's key — see verify-kdf.mjs.)
+export const STATIC_POINT_COMPRESSED = Buffer.from(
+  '0328081290396d063e5114526ed978b926558f6ba1c96ad2facf76fffb3ffea0fe', 'hex');
+export const STATIC_POINT_X = STATIC_POINT_COMPRESSED.subarray(1, 33).toString('hex');
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+const rev = (b) => Buffer.from(b).reverse();
+const pad32 = (b) => (b.length >= 32 ? b.subarray(b.length - 32) : Buffer.concat([Buffer.alloc(32 - b.length), b]));
+
+/** SEC1-decompress a 33-byte compressed point to a 65-byte uncompressed point. */
+export function decompressPoint(compressed33) {
+  const { p, a, b } = P256;
+  const prefix = compressed33[0];
+  const x = BigInt('0x' + compressed33.subarray(1, 33).toString('hex'));
+  const rhs = (((x * x % p) * x % p) + a * x % p + b) % p;
+  let y = modpow(rhs, (p + 1n) / 4n, p);          // p ≡ 3 (mod 4)
+  if ((y * y) % p !== rhs) throw new Error('static point X is not on P-256');
+  if ((y & 1n) !== BigInt(prefix & 1)) y = p - y; // pick parity from prefix bit0
+  const hex = (v) => v.toString(16).padStart(64, '0');
+  return Buffer.from('04' + hex(x) + hex(y), 'hex');
+}
+
+function modpow(base, exp, mod) {
+  let r = 1n; base %= mod;
+  while (exp > 0n) { if (exp & 1n) r = r * base % mod; base = base * base % mod; exp >>= 1n; }
+  return r;
+}
+
+// ── wire encoding for the opcode-0x0F public-key exchange ────────────────────
+// On the wire each point is 64 bytes: X (little-endian) ‖ Y (little-endian).
+
+/** uncompressed SEC1 point (65B, 0x04‖Xbe‖Ybe) → 64-byte little-endian wire form */
+export function pointToWire(uncompressed65) {
+  const xbe = uncompressed65.subarray(1, 33);
+  const ybe = uncompressed65.subarray(33, 65);
+  return Buffer.concat([rev(xbe), rev(ybe)]);
+}
+
+/** 64-byte little-endian wire point → uncompressed SEC1 point (65B) for node crypto */
+export function wireToPoint(wire64) {
+  const xbe = rev(wire64.subarray(0, 32));
+  const ybe = rev(wire64.subarray(32, 64));
+  return Buffer.concat([Buffer.from([0x04]), xbe, ybe]);
+}
+
+// ── the KDF ─────────────────────────────────────────────────────────────────
+
+/** Create the ephemeral P-256 keypair (step 1–2 of the KDF). */
+export function makeEphemeral() {
+  const ecdh = crypto.createECDH('prime256v1');
+  ecdh.generateKeys();
+  return ecdh;
+}
+
+/**
+ * Derive the per-session AES-256 key.
+ *   key = LE( X(d·S)  XOR  X(d·Q) )
+ * @param ecdh         our ephemeral ECDH object (the private scalar d)
+ * @param stickPub65   the Stick's public key Q, uncompressed (65B, 0x04‖X‖Y)
+ * @returns 32-byte Buffer — the AES-256 key as the Stick installs it
+ */
+export function deriveDmxKey(ecdh, stickPub65) {
+  const S = decompressPoint(STATIC_POINT_COMPRESSED);
+  const x1 = pad32(ecdh.computeSecret(S));          // X(d·S), big-endian
+  const x2 = pad32(ecdh.computeSecret(stickPub65)); // X(d·Q), big-endian
+  const xorBE = Buffer.alloc(32);
+  for (let i = 0; i < 32; i++) xorBE[i] = x1[i] ^ x2[i];
+  return rev(xorBE); // Stick stores the key in little-endian limb order
+}
+
+// ── self-test ────────────────────────────────────────────────────────────────
+function selfTest() {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}`); ok &&= cond; };
+
+  console.log('Stick-DE3 DMX key-derivation — self-test\n');
+
+  // 1. static point is valid on P-256
+  const S = decompressPoint(STATIC_POINT_COMPRESSED);
+  check('static point S decompresses & lies on P-256', S.length === 65 && S[0] === 0x04);
+
+  // 2. ECDH symmetry: client and Stick derive the SAME key.
+  //    The real S has an unknown private; model it with a generated keypair.
+  const staticKp = crypto.createECDH('prime256v1'); staticKp.generateKeys();   // (s, S)
+  const stickEph = crypto.createECDH('prime256v1'); stickEph.generateKeys();   // (e, Q)
+  const Spub = staticKp.getPublicKey(null, 'uncompressed');
+  const Qpub = stickEph.getPublicKey(null, 'uncompressed');
+
+  const client = makeEphemeral();                       // (d, our)
+  const ourPub = client.getPublicKey(null, 'uncompressed');
+
+  // client side: X(d·S) XOR X(d·Q)
+  const clientKey = (() => {
+    const x1 = pad32(client.computeSecret(Spub));
+    const x2 = pad32(client.computeSecret(Qpub));
+    const o = Buffer.alloc(32);
+    for (let i = 0; i < 32; i++) o[i] = x1[i] ^ x2[i];
+    return rev(o);
+  })();
+  // stick side: X(s·our) XOR X(e·our)
+  const stickKey = (() => {
+    const x1 = pad32(staticKp.computeSecret(ourPub));
+    const x2 = pad32(stickEph.computeSecret(ourPub));
+    const o = Buffer.alloc(32);
+    for (let i = 0; i < 32; i++) o[i] = x1[i] ^ x2[i];
+    return rev(o);
+  })();
+  check('client & Stick derive identical key (ECDH symmetry)', clientKey.equals(stickKey));
+  check('derived key is 32 bytes (AES-256)', clientKey.length === 32);
+
+  // 3. wire round-trip
+  const wire = pointToWire(Qpub);
+  check('point ⇄ wire round-trips', wireToPoint(wire).equals(Qpub) && wire.length === 64);
+
+  // 4. exercise deriveDmxKey() with the REAL static point
+  const k = deriveDmxKey(makeEphemeral(), Qpub);
+  check('deriveDmxKey() runs with real S, yields 32B', k.length === 32);
+
+  console.log(`\n${ok ? 'ALL TESTS PASSED' : 'TESTS FAILED'}`);
+  process.exit(ok ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) selfTest();

package/tools/diff-011c.mjs

@@ -0,0 +1,127 @@
+// Byte-by-byte diff of every 0x011c S->C reply across one or more pcaps.
+// Identifies which byte positions are constant across sessions vs which
+// vary -- so we know exactly which bytes inside that 258-byte payload
+// HWM might be reading as session-state vs structure.
+//
+//   node tools/diff-011c.mjs <pcap> [<pcap>...]
+
+import fs from 'node:fs';
+
+function ipFromEth(pkt) {
+  if (pkt.length < 14) return null;
+  let off = 12;
+  let eth = pkt.readUInt16BE(off);
+  for (let i = 0; i < 2 && eth === 0x8100; i++) {
+    off += 4; if (off + 2 > pkt.length) return null;
+    eth = pkt.readUInt16BE(off);
+  }
+  if (eth !== 0x0800) return null;
+  return pkt.subarray(off + 2);
+}
+
+function reassemble(segs) {
+  if (!segs.length) return Buffer.alloc(0);
+  segs.sort((a, b) => (a.seq - b.seq + 0x100000000) % 0x100000000);
+  const seen = new Set();
+  let base = segs[0].seq;
+  const out = [];
+  for (const s of segs) {
+    const k = `${s.seq}:${s.payload.length}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    const off = (s.seq - base + 0x100000000) % 0x100000000;
+    while (out.length < off + s.payload.length) out.push(0);
+    for (let i = 0; i < s.payload.length; i++) out[off + i] = s.payload[i];
+  }
+  return Buffer.from(out);
+}
+
+function extractReplies(pcapPath) {
+  const buf = fs.readFileSync(pcapPath);
+  const magic = buf.readUInt32LE(0);
+  const le = magic === 0xa1b2c3d4;
+  if (!le && magic !== 0xd4c3b2a1) return [];
+  const streams = new Map();
+  let off = 24;
+  while (off + 16 <= buf.length) {
+    const capLen = le ? buf.readUInt32LE(off + 8) : buf.readUInt32BE(off + 8);
+    off += 16;
+    if (off + capLen > buf.length) break;
+    const pkt = buf.subarray(off, off + capLen); off += capLen;
+    const ip = ipFromEth(pkt);
+    if (!ip || ip.length < 20 || ((ip[0] >> 4) & 0xf) !== 4) continue;
+    const ihl = (ip[0] & 0x0f) * 4;
+    if (ip[9] !== 6) continue;
+    const tcp = ip.subarray(ihl);
+    const sp = tcp.readUInt16BE(0), dp = tcp.readUInt16BE(2);
+    if (sp !== 2431) continue;                         // S->C only
+    const seq = tcp.readUInt32BE(4);
+    const dataOff = (tcp[12] >> 4) * 4;
+    const payload = tcp.subarray(dataOff);
+    if (!payload.length) continue;
+    const src = `${ip[12]}.${ip[13]}.${ip[14]}.${ip[15]}:${sp}`;
+    const dst = `${ip[16]}.${ip[17]}.${ip[18]}.${ip[19]}:${dp}`;
+    const k = [src, dst].sort().join('<->');
+    if (!streams.has(k)) streams.set(k, []);
+    streams.get(k).push({ seq, payload });
+  }
+  const replies = [];
+  for (const [k, segs] of streams) {
+    const reassembled = reassemble(segs);
+    for (let i = 0; i + 10 <= reassembled.length; i++) {
+      const m = reassembled.subarray(i, i + 8).toString();
+      if (m !== 'Stick_3A' && m !== 'LSAG_ALL') continue;
+      if (reassembled.readUInt16LE(i + 8) !== 0x011c) continue;
+      // length-prefix at +0x14
+      if (i + 0x18 > reassembled.length) continue;
+      const len = reassembled.readUInt32LE(i + 0x14);
+      if (len < 0x18 || len > 0x400 || i + len > reassembled.length) continue;
+      replies.push({ pcap: pcapPath, stream: k, msg: reassembled.subarray(i, i + len) });
+    }
+  }
+  return replies;
+}
+
+const all = [];
+for (const pcap of process.argv.slice(2)) {
+  const reps = extractReplies(pcap);
+  console.log(`${pcap}: ${reps.length} 0x011c replies`);
+  all.push(...reps);
+}
+if (all.length < 2) { console.error('need >= 2 replies to diff'); process.exit(1); }
+
+const L = Math.min(...all.map((r) => r.msg.length));
+console.log(`\nshortest = ${L}B; diffing ${all.length} replies position-by-position\n`);
+
+// Constant vs variable map.
+const ranges = [];   // [{start,end,kind: 'const'|'var', vals?}]
+let cur = null;
+for (let i = 0; i < L; i++) {
+  const vals = new Set(all.map((r) => r.msg[i]));
+  const kind = vals.size === 1 ? 'const' : 'var';
+  if (!cur || cur.kind !== kind) {
+    if (cur) ranges.push(cur);
+    cur = { start: i, end: i, kind, vals };
+  } else {
+    cur.end = i;
+    if (kind === 'const') cur.vals = vals;
+  }
+}
+if (cur) ranges.push(cur);
+
+console.log('=== regions ===');
+for (const r of ranges) {
+  if (r.kind === 'const') {
+    const v = all[0].msg.subarray(r.start, r.end + 1).toString('hex');
+    console.log(`  +0x${r.start.toString(16).padStart(3,'0')}..+0x${r.end.toString(16).padStart(3,'0')}  (${r.end-r.start+1}B)  CONST = ${v}`);
+  } else {
+    console.log(`  +0x${r.start.toString(16).padStart(3,'0')}..+0x${r.end.toString(16).padStart(3,'0')}  (${r.end-r.start+1}B)  variable`);
+  }
+}
+
+// Side-by-side first 64 bytes of payload (after the 0x1c header).
+console.log('\n=== first 64B of payload (offset 0x1c..0x5c) per session ===');
+for (const r of all) {
+  const tag = r.pcap.split('/').pop() + ' tok=' + r.msg.readUInt32LE(0x0a);
+  console.log(`  ${tag.padEnd(34)} ${r.msg.subarray(0x1c, 0x5c).toString('hex')}`);
+}

package/tools/dump-pcap-summary.mjs

@@ -0,0 +1,54 @@
+// Quick summary of every packet in a pcap, with TCP/UDP demux and payload preview.
+
+import fs from 'node:fs';
+
+const [, , pcapPath] = process.argv;
+if (!pcapPath) { console.error('usage: node dump-pcap-summary.mjs <file.pcap>'); process.exit(1); }
+
+const buf = fs.readFileSync(pcapPath);
+const magic = buf.readUInt32LE(0);
+const le = magic === 0xa1b2c3d4 ? true : magic === 0xd4c3b2a1 ? false : null;
+if (le === null) { console.error('not a pcap'); process.exit(2); }
+const linkType = le ? buf.readUInt32LE(20) : buf.readUInt32BE(20);
+const ethSkip = linkType === 1 ? 14 : 4;
+
+let off = 24, idx = 0;
+while (off + 16 <= buf.length) {
+  const tsSec  = le ? buf.readUInt32LE(off)     : buf.readUInt32BE(off);
+  const tsUsec = le ? buf.readUInt32LE(off + 4) : buf.readUInt32BE(off + 4);
+  const capLen = le ? buf.readUInt32LE(off + 8) : buf.readUInt32BE(off + 8);
+  off += 16;
+  if (off + capLen > buf.length) break;
+  const pkt = buf.subarray(off, off + capLen);
+  off += capLen;
+  idx++;
+
+  if (pkt.length < ethSkip + 20) continue;
+  const ip = pkt.subarray(ethSkip);
+  if (((ip[0] >> 4) & 0xf) !== 4) continue;
+  const ihl = (ip[0] & 0x0f) * 4;
+  const proto = ip[9];
+  const srcIp = `${ip[12]}.${ip[13]}.${ip[14]}.${ip[15]}`;
+  const dstIp = `${ip[16]}.${ip[17]}.${ip[18]}.${ip[19]}`;
+  const l4 = ip.subarray(ihl);
+  const ts = `${tsSec}.${String(tsUsec).padStart(6,'0')}`;
+  if (proto === 6) {           // TCP
+    const sp = l4.readUInt16BE(0), dp = l4.readUInt16BE(2);
+    const flags = l4[13];
+    const fStr = [
+      flags&0x02?'S':'', flags&0x10?'A':'', flags&0x08?'P':'',
+      flags&0x01?'F':'', flags&0x04?'R':''
+    ].join('');
+    const dataOff = (l4[12] >> 4) * 4;
+    const payload = l4.subarray(dataOff);
+    console.log(`#${idx} ${ts} TCP ${srcIp}:${sp} -> ${dstIp}:${dp} [${fStr}] payload=${payload.length}B${payload.length?'  '+payload.subarray(0,40).toString('hex'):''}`);
+  } else if (proto === 17) {   // UDP
+    const sp = l4.readUInt16BE(0), dp = l4.readUInt16BE(2);
+    const ulen = l4.readUInt16BE(4) - 8;
+    const payload = l4.subarray(8, 8+ulen);
+    const preview = payload.length > 32 ? payload.subarray(0,32).toString('hex')+'...' : payload.toString('hex');
+    console.log(`#${idx} ${ts} UDP ${srcIp}:${sp} -> ${dstIp}:${dp} payload=${ulen}B  ${preview}`);
+  } else {
+    console.log(`#${idx} ${ts} proto=${proto} ${srcIp}->${dstIp}`);
+  }
+}

package/tools/dump-tcp-stream.mjs

@@ -0,0 +1,123 @@
+// TCP stream reassembler for the Stick-DE3 TCP/2431 control channel.
+//
+// Pulls ALL payload bytes from both directions, in order, and prints them
+// as labelled message frames. The Stick's protocol has a clean "magic +
+// opcode" header on each application message, so we can chunk by parsing
+// the magic alone.
+//
+// Output: one block per application message:
+//   [time] DIR len=N  magic+opcode header  + full hex dump
+
+import fs from 'node:fs';
+
+const [, , pcapPath] = process.argv;
+if (!pcapPath) { console.error('usage: node dump-tcp-stream.mjs <file.pcap>'); process.exit(1); }
+
+const STICK_IP   = process.env.STICK_IP   || '192.168.96.2';
+const STICK_PORT = Number(process.env.STICK_PORT || 2431);
+
+const buf = fs.readFileSync(pcapPath);
+const magic = buf.readUInt32LE(0);
+const le = magic === 0xa1b2c3d4 ? true : magic === 0xd4c3b2a1 ? false : null;
+if (le === null) { console.error('not a pcap'); process.exit(2); }
+const linkType = le ? buf.readUInt32LE(20) : buf.readUInt32BE(20);
+const ethSkip = linkType === 1 ? 14 : 4;
+
+// Gather all TCP payload chunks in order with direction + timestamp.
+const chunks = [];
+let off = 24;
+while (off + 16 <= buf.length) {
+  const tsSec  = le ? buf.readUInt32LE(off)     : buf.readUInt32BE(off);
+  const tsUsec = le ? buf.readUInt32LE(off + 4) : buf.readUInt32BE(off + 4);
+  const capLen = le ? buf.readUInt32LE(off + 8) : buf.readUInt32BE(off + 8);
+  off += 16;
+  if (off + capLen > buf.length) break;
+  const pkt = buf.subarray(off, off + capLen);
+  off += capLen;
+  if (pkt.length < ethSkip + 20) continue;
+  const ip = pkt.subarray(ethSkip);
+  if (((ip[0] >> 4) & 0xf) !== 4) continue;
+  const ihl = (ip[0] & 0x0f) * 4;
+  const proto = ip[9];
+  if (proto !== 6) continue;
+  const srcIp = `${ip[12]}.${ip[13]}.${ip[14]}.${ip[15]}`;
+  const dstIp = `${ip[16]}.${ip[17]}.${ip[18]}.${ip[19]}`;
+  const tcp = ip.subarray(ihl);
+  if (tcp.length < 20) continue;
+  const sp = tcp.readUInt16BE(0), dp = tcp.readUInt16BE(2);
+  const dataOff = (tcp[12] >> 4) * 4;
+  const payload = tcp.subarray(dataOff);
+  if (payload.length === 0) continue;
+  if (!((srcIp === STICK_IP && sp === STICK_PORT) || (dstIp === STICK_IP && dp === STICK_PORT))) continue;
+  const dir = (srcIp === STICK_IP) ? 'S→C' : 'C→S';
+  chunks.push({ ts: `${tsSec}.${String(tsUsec).padStart(6,'0')}`, dir, payload });
+}
+
+// Re-chunk by application message: each message starts with 8-byte magic
+// "LSAG_ALL" or "Stick_3A". Concatenate contiguous same-direction chunks,
+// then split by magic occurrences.
+function chunkByMagic(data) {
+  const out = [];
+  let i = 0;
+  while (i < data.length) {
+    // Find next magic at i (must be at start of message)
+    const m1 = data.indexOf(Buffer.from('LSAG_ALL'), i);
+    const m2 = data.indexOf(Buffer.from('Stick_3A'), i);
+    const next = (m1 === -1) ? m2 : (m2 === -1) ? m1 : Math.min(m1, m2);
+    if (next === -1) { out.push(data.subarray(i)); break; }
+    if (next > i) out.push(data.subarray(i, next));
+    // Find end = next magic after `next`
+    const a = data.indexOf(Buffer.from('LSAG_ALL'), next + 8);
+    const b = data.indexOf(Buffer.from('Stick_3A'), next + 8);
+    const end = (a === -1) ? b : (b === -1) ? a : Math.min(a, b);
+    if (end === -1) { out.push(data.subarray(next)); break; }
+    out.push(data.subarray(next, end));
+    i = end;
+  }
+  return out;
+}
+
+// Run the dir state machine
+let stream = { 'C→S': Buffer.alloc(0), 'S→C': Buffer.alloc(0) };
+let msgCount = 0;
+for (const c of chunks) {
+  stream[c.dir] = Buffer.concat([stream[c.dir], c.payload]);
+  // Try to consume complete messages from this direction
+  const msgs = chunkByMagic(stream[c.dir]);
+  if (msgs.length > 1) {
+    for (let i = 0; i < msgs.length - 1; i++) {
+      msgCount++;
+      const m = msgs[i];
+      const magic = m.length >= 8 ? m.subarray(0, 8).toString('latin1') : '???';
+      const opcode = m.length >= 10 ? m.readUInt16LE(8).toString(16).padStart(4,'0') : '?';
+      console.log(`[${c.ts}] msg#${msgCount} ${c.dir} ${m.length}B  magic="${magic}" opcode=0x${opcode}`);
+      // Full hex dump in rows of 16
+      for (let off = 0; off < m.length; off += 16) {
+        const row = m.subarray(off, off + 16);
+        const hex = Array.from(row).map(b => b.toString(16).padStart(2, '0')).join(' ');
+        const ascii = Array.from(row).map(b => b >= 32 && b < 127 ? String.fromCharCode(b) : '.').join('');
+        console.log(`    ${off.toString(16).padStart(4,'0')}: ${hex.padEnd(48)}  |${ascii}|`);
+      }
+      console.log();
+    }
+    stream[c.dir] = msgs[msgs.length - 1];
+  }
+}
+// Flush any leftover partial messages
+for (const dir of ['C→S', 'S→C']) {
+  if (stream[dir].length) {
+    msgCount++;
+    const m = stream[dir];
+    const magic = m.length >= 8 ? m.subarray(0, 8).toString('latin1') : '???';
+    const opcode = m.length >= 10 ? m.readUInt16LE(8).toString(16).padStart(4,'0') : '?';
+    console.log(`[flush] msg#${msgCount} ${dir} ${m.length}B  magic="${magic}" opcode=0x${opcode}`);
+    for (let off = 0; off < m.length; off += 16) {
+      const row = m.subarray(off, off + 16);
+      const hex = Array.from(row).map(b => b.toString(16).padStart(2, '0')).join(' ');
+      const ascii = Array.from(row).map(b => b >= 32 && b < 127 ? String.fromCharCode(b) : '.').join('');
+      console.log(`    ${off.toString(16).padStart(4,'0')}: ${hex.padEnd(48)}  |${ascii}|`);
+    }
+    console.log();
+  }
+}
+console.log(`# total messages: ${msgCount}`);

package/tools/extract-011c.mjs

@@ -0,0 +1,117 @@
+// Extract every TCP/2431 message with opcode 0x011c from a pcap.
+//
+// Both directions: client->Stick (request body, if any) and Stick->client
+// (the 263-byte session-unique reply blob we don't decode). Strips 802.1Q
+// tags so it works on the UniFi-mirror pcaps as well as laptop captures.
+//
+//   node tools/extract-011c.mjs <file.pcap>
+
+import fs from 'node:fs';
+
+const [, , pcapPath] = process.argv;
+if (!pcapPath) { console.error('usage: node tools/extract-011c.mjs <file.pcap>'); process.exit(1); }
+
+const buf = fs.readFileSync(pcapPath);
+const magic = buf.readUInt32LE(0);
+const le = magic === 0xa1b2c3d4;
+if (!le && magic !== 0xd4c3b2a1) { console.error('bad pcap'); process.exit(2); }
+
+// IP-level walker that handles 802.1Q-tagged frames too.
+function ipFromEth(pkt) {
+  if (pkt.length < 14) return null;
+  let off = 12;
+  let eth = pkt.readUInt16BE(off);
+  // walk up to 2 VLAN tags
+  for (let i = 0; i < 2 && eth === 0x8100; i++) {
+    off += 4;
+    if (off + 2 > pkt.length) return null;
+    eth = pkt.readUInt16BE(off);
+  }
+  if (eth !== 0x0800) return null;
+  return pkt.subarray(off + 2);
+}
+
+// Reassemble per-connection TCP streams so an 0x011c reply that spans
+// segments still surfaces as one message.
+const streams = new Map();   // key -> { c2s: {seq0,buf}, s2c: {seq0,buf} }
+
+let off = 24;
+while (off + 16 <= buf.length) {
+  const capLen = le ? buf.readUInt32LE(off + 8) : buf.readUInt32BE(off + 8);
+  const tsSec = le ? buf.readUInt32LE(off) : buf.readUInt32BE(off);
+  const tsUsec = le ? buf.readUInt32LE(off + 4) : buf.readUInt32BE(off + 4);
+  off += 16;
+  if (off + capLen > buf.length) break;
+  const pkt = buf.subarray(off, off + capLen);
+  off += capLen;
+  const ip = ipFromEth(pkt);
+  if (!ip || ip.length < 20) continue;
+  if (((ip[0] >> 4) & 0xf) !== 4) continue;
+  const ihl = (ip[0] & 0x0f) * 4;
+  if (ip[9] !== 6) continue;       // TCP only
+  const tcp = ip.subarray(ihl);
+  const sp = tcp.readUInt16BE(0), dp = tcp.readUInt16BE(2);
+  if (sp !== 2431 && dp !== 2431) continue;
+  const seq = tcp.readUInt32BE(4);
+  const dataOff = (tcp[12] >> 4) * 4;
+  const payload = tcp.subarray(dataOff);
+  if (payload.length === 0) continue;
+  const src = `${ip[12]}.${ip[13]}.${ip[14]}.${ip[15]}:${sp}`;
+  const dst = `${ip[16]}.${ip[17]}.${ip[18]}.${ip[19]}:${dp}`;
+  const cs = [src, dst].sort().join(' <-> ');
+  if (!streams.has(cs)) streams.set(cs, { c2s: [], s2c: [], t0: tsSec + tsUsec / 1e6 });
+  const dir = sp === 2431 ? 's2c' : 'c2s';
+  streams.get(cs)[dir].push({ seq, payload, t: tsSec + tsUsec / 1e6 });
+}
+
+function reassemble(segments) {
+  if (!segments.length) return Buffer.alloc(0);
+  segments.sort((a, b) => (a.seq - b.seq + 0x100000000) % 0x100000000);
+  // De-dup retransmits (same seq, same length).
+  const seen = new Set();
+  const parts = [];
+  let base = segments[0].seq;
+  let cursor = base;
+  for (const s of segments) {
+    const k = `${s.seq}:${s.payload.length}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    const off = (s.seq - base + 0x100000000) % 0x100000000;
+    while (parts.length < off + s.payload.length) parts.push(0);
+    for (let i = 0; i < s.payload.length; i++) parts[off + i] = s.payload[i];
+  }
+  return Buffer.from(parts);
+}
+
+// Walk a reassembled stream looking for messages by the 8-byte magic
+// (Stick_3A or LSAG_ALL) followed by 2-byte LE opcode == 0x011c.
+function scan(direction, key, segs) {
+  const buf = reassemble(segs);
+  for (let i = 0; i + 10 <= buf.length; i++) {
+    const m = buf.subarray(i, i + 8).toString();
+    if (m !== 'Stick_3A' && m !== 'LSAG_ALL') continue;
+    const op = buf.readUInt16LE(i + 8);
+    if (op !== 0x011c) continue;
+    // We don't know the length-prefix scheme universally, but we can
+    // print everything from this magic to the next magic (or end).
+    let j = i + 10;
+    while (j + 8 <= buf.length) {
+      const mm = buf.subarray(j, j + 8).toString();
+      if (mm === 'Stick_3A' || mm === 'LSAG_ALL') break;
+      j++;
+    }
+    const msg = buf.subarray(i, j);
+    console.log(`\n--- ${key}  ${direction}  opcode=0x011c  len=${msg.length}B ---`);
+    console.log(`magic=${m}  token=${buf.readUInt32LE(i + 10)}  bytes:`);
+    for (let k = 0; k < msg.length; k += 32) {
+      const row = msg.subarray(k, Math.min(k + 32, msg.length));
+      console.log(`  ${k.toString().padStart(4)} : ${row.toString('hex')}`);
+    }
+  }
+}
+
+console.log(`pcap ${pcapPath}: ${streams.size} TCP/2431 stream(s)`);
+for (const [k, s] of streams) {
+  scan('S->C', k, s.s2c);
+  scan('C->S', k, s.c2s);
+}