@ecopoesis/homebridge-dmx 0.1.0

package/tools/analyze-pcap.mjs

@@ -0,0 +1,143 @@
+// Deep analysis of a Stick-DE3 pcap: TCP connections + per-connection opcode
+// timeline, and UDP DMX-frame header statistics (fieldA / seq progression,
+// the +0x12 port field, timing). Built to diff a real Hardware Manager
+// session against our send_dmx run.
+//
+//   node tools/analyze-pcap.mjs <file.pcap>
+
+import fs from 'node:fs';
+
+const [, , pcapPath] = process.argv;
+if (!pcapPath) { console.error('usage: node tools/analyze-pcap.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); }
+const linkType = le ? buf.readUInt32LE(20) : buf.readUInt32BE(20);
+const ethSkip = linkType === 1 ? 14 : 4;
+
+const pkts = [];
+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];
+  const src = `${ip[12]}.${ip[13]}.${ip[14]}.${ip[15]}`;
+  const dst = `${ip[16]}.${ip[17]}.${ip[18]}.${ip[19]}`;
+  const l4 = ip.subarray(ihl);
+  const t = tsSec + tsUsec / 1e6;
+  if (proto === 6) {
+    const sp = l4.readUInt16BE(0), dp = l4.readUInt16BE(2);
+    const flags = l4[13];
+    const dataOff = (l4[12] >> 4) * 4;
+    pkts.push({ t, proto: 'TCP', src, dst, sp, dp, flags, payload: Buffer.from(l4.subarray(dataOff)) });
+  } else if (proto === 17) {
+    const sp = l4.readUInt16BE(0), dp = l4.readUInt16BE(2);
+    const ulen = l4.readUInt16BE(4) - 8;
+    pkts.push({ t, proto: 'UDP', src, dst, sp, dp, payload: Buffer.from(l4.subarray(8, 8 + ulen)) });
+  }
+}
+
+const t0 = pkts.length ? pkts[0].t : 0;
+const rel = (t) => (t - t0).toFixed(3).padStart(9);
+
+// ── TCP connections ─────────────────────────────────────────────────────────
+console.log(`\n=== ${pcapPath} ===`);
+console.log(`${pkts.length} IP packets, span ${(pkts[pkts.length-1].t - t0).toFixed(1)}s\n`);
+
+const conns = new Map();
+for (const p of pkts) {
+  if (p.proto !== 'TCP') continue;
+  const key = [p.src + ':' + p.sp, p.dst + ':' + p.dp].sort().join(' <-> ');
+  if (!conns.has(key)) conns.set(key, []);
+  conns.get(key).push(p);
+}
+console.log(`TCP connections: ${conns.size}`);
+for (const [key, ps] of conns) {
+  const dur = ps[ps.length - 1].t - ps[0].t;
+  const dataP = ps.filter((p) => p.payload.length > 0);
+  console.log(`\n  ${key}   start=${rel(ps[0].t)}s  dur=${dur.toFixed(3)}s  pkts=${ps.length} (${dataP.length} w/ payload)`);
+  for (const p of dataP) {
+    const dir = p.sp === 2431 ? 'S->C' : 'C->S';
+    let op = '';
+    const pl = p.payload;
+    if (pl.length >= 10 && (pl.subarray(0,8).toString()==='Stick_3A' || pl.subarray(0,8).toString()==='LSAG_ALL')) {
+      op = `op=0x${pl.readUInt16LE(8).toString(16).padStart(4,'0')}`;
+    }
+    console.log(`    ${rel(p.t)}  ${dir}  ${String(pl.length).padStart(4)}B  ${op.padEnd(11)} ${pl.subarray(0,28).toString('hex')}`);
+  }
+}
+
+// ── UDP DMX frames ──────────────────────────────────────────────────────────
+const dmx = pkts.filter((p) => p.proto === 'UDP' && p.payload.length === 576);
+console.log(`\n\nUDP 576-byte DMX frames: ${dmx.length}`);
+if (dmx.length) {
+  const f = dmx[0], h = f.payload;
+  console.log(`  src ${f.src}:${f.sp} -> dst ${f.dst}:${f.dp}`);
+  console.log(`  first frame header (32B): ${h.subarray(0,32).toString('hex')}`);
+  const fieldA0 = h.readUInt32LE(0x0a);
+  console.log(`  +0x08 opcode    = 0x${h.readUInt16LE(8).toString(16)}`);
+  console.log(`  +0x0a fieldA    = ${fieldA0} (0x${fieldA0.toString(16)})  [8B: ${h.subarray(0x0a,0x12).toString('hex')}]`);
+  console.log(`  +0x12 port      = ${h.readUInt16LE(0x12)}`);
+  console.log(`  +0x14 chanCount = ${h.readUInt16LE(0x14)}`);
+  console.log(`  +0x16 const     = ${h[0x16]}`);
+  console.log(`  +0x17 seq       = ${h[0x17]}`);
+  console.log(`  +0x18 nonce     = ${h.subarray(0x18,0x20).toString('hex')}`);
+
+  // progressions
+  let dT = [], dA = [], dS = [], ports = new Set(), chans = new Set();
+  for (let i = 1; i < dmx.length; i++) {
+    dT.push(dmx[i].t - dmx[i-1].t);
+    let a = dmx[i].payload.readUInt32LE(0x0a) - dmx[i-1].payload.readUInt32LE(0x0a);
+    let s = dmx[i].payload[0x17] - dmx[i-1].payload[0x17];
+    if (s < 0) s += 256;
+    dA.push(a); dS.push(s);
+  }
+  for (const p of dmx) { ports.add(p.payload.readUInt16LE(0x12)); chans.add(p.payload.readUInt16LE(0x14)); }
+  const uniq = (arr) => [...new Set(arr)].sort((a,b)=>a-b);
+  const avg = (arr) => arr.reduce((s,x)=>s+x,0)/arr.length;
+  console.log(`\n  fieldA delta/frame : ${uniq(dA).join(',')}   (start ${fieldA0}, end ${dmx[dmx.length-1].payload.readUInt32LE(0x0a)})`);
+  console.log(`  seq    delta/frame : ${uniq(dS).join(',')}`);
+  console.log(`  +0x12 port values  : ${[...ports].join(',')}`);
+  console.log(`  +0x14 chanCount    : ${[...chans].join(',')}`);
+  console.log(`  inter-frame gap    : avg ${(avg(dT)*1000).toFixed(1)}ms  (${(1/avg(dT)).toFixed(1)} Hz)`);
+  console.log(`  first DMX frame at : ${rel(dmx[0].t)}s    last at ${rel(dmx[dmx.length-1].t)}s`);
+
+  // ── unified-counter contiguity check ──────────────────────────────────────
+  // HWM draws fieldA (UDP) and the TCP token from ONE monotonic counter.
+  // Build a merged time-ordered list of (TCP token) + (UDP fieldA) and verify
+  // the UDP frames continue the TCP token sequence without going backwards.
+  const tcpTok = [];
+  for (const p of pkts) {
+    if (p.proto !== 'TCP' || p.payload.length < 18) continue;
+    const m = p.payload.subarray(0, 8).toString();
+    if (m !== 'Stick_3A' && m !== 'LSAG_ALL') continue;
+    if (p.sp === 2431) continue;                       // client->Stick only
+    const op = p.payload.readUInt16LE(8);
+    tcpTok.push({ t: p.t, kind: 'TCP', op, val: p.payload.readUInt32LE(10) });
+  }
+  const merged = [...tcpTok, ...dmx.map((p) => ({ t: p.t, kind: 'UDP', val: p.payload.readUInt32LE(0x0a) }))]
+    .sort((a, b) => a.t - b.t);
+  // last TCP token before the first UDP frame
+  const firstUdpT = dmx[0].t;
+  const tcpBefore = tcpTok.filter((x) => x.t < firstUdpT);
+  const lastTok = tcpBefore.length ? tcpBefore[tcpBefore.length - 1].val : null;
+  console.log(`\n  unified counter:`);
+  console.log(`    last TCP token before 1st UDP frame : ${lastTok}`);
+  console.log(`    first UDP fieldA                    : ${dmx[0].payload.readUInt32LE(0x0a)}`);
+  let backwards = 0, prev = -1;
+  for (const e of merged) { if (e.val < prev) backwards++; prev = Math.max(prev, e.val); }
+  const contiguous = lastTok != null && dmx[0].payload.readUInt32LE(0x0a) === lastTok + 1;
+  console.log(`    UDP fieldA == lastTCPtoken + 1 ?    : ${contiguous ? 'YES' : 'NO'}`);
+  console.log(`    backwards steps in merged sequence  : ${backwards} ${backwards ? '<-- Stick will drop these' : '(monotonic OK)'}`);
+}

package/tools/capture-aes-key.lldb

@@ -0,0 +1,25 @@
+# Capture the Stick-DE3 DMX AES-128 key from the SYMBOLIZED old HardwareManager.
+#
+# Target: 2024-03-21 ESA2 build (symbol-rich; NOT the stripped EsaPro2 one).
+# Gladman AES: aes_encrypt_key128(const u8 *key, aes_encrypt_ctx *cx)
+#   x86_64 SysV at entry:  $rdi = ptr to 16-byte raw key,  $rsi = ctx
+#
+# ATTACH workflow (launch-under-lldb fails: Rosetta + hardened runtime):
+#   1. Open ESA2 Hardware Manager normally. Do NOT connect the Stick yet.
+#   2. PID=$(pgrep -f 'ESA2/HardwareManager/HardwareManager.app.*HardwareManager$')
+#   3. lldb -p "$PID" -s tools/capture-aes-key.lldb
+#   4. After it prints "continuing — connect the Stick now", in Hardware
+#      Manager connect to the Stick (192.168.96.2) and start DMX/live output.
+#
+# Each aes_encrypt_key128 hit prints the 16-byte key + caller backtrace
+# (the backtrace = the per-session key-derivation chain for the plugin).
+# IV not needed live: IV = aes_decrypt(C0) XOR P0 from a captured 576B frame.
+
+break set -n aes_encrypt_key128
+break command add -o "memory read --size 1 --format x --count 16 $rdi" -o "register read rdi rsi" -o "thread backtrace -c 16" -o "continue" 1
+
+break set -n aes_encrypt_key
+break command add -o "memory read --size 1 --format x --count 16 $rdi" -o "register read rdi rsi" -o "thread backtrace -c 16" -o "continue" 2
+
+script print(">>> breakpoints armed; continuing — connect the Stick now <<<")
+continue

package/tools/capture-and-verify.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Capture ONE encrypted DMX frame from the live Stick stream, then try to
+# decrypt it with the hardcoded 33-byte secret discovered via Ghidra.
+#
+# Prereqs (already installed):
+#   - tcpdump  (built-in on macOS)
+#   - node     (for the pcap parser + decrypt test)
+# That's it. No tshark, no tsx.
+#
+# Setup:
+#   1. Open Hardware Manager and connect to the Stick at 192.168.96.2.
+#   2. Open the DMX/fader screen so HWM is actively streaming live DMX.
+#   3. Run this script. It needs sudo for tcpdump's raw socket.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+IFACE="${IFACE:-en0}"
+STICK_IP="${STICK_IP:-192.168.96.2}"
+STICK_PORT="${STICK_PORT:-2431}"
+DUR="${DUR:-3}"
+PCAP=/tmp/stick-dmx.pcap
+FRAME=/tmp/stick-dmx-frame.bin
+
+echo ">>> Capturing ${DUR}s of UDP→${STICK_IP}:${STICK_PORT} on ${IFACE}"
+echo ">>> (HWM must be connected + streaming DMX right now)"
+sudo tcpdump -i "$IFACE" -w "$PCAP" -G "$DUR" -W 1 \
+  "udp and host ${STICK_IP} and port ${STICK_PORT}" \
+  2>/dev/null || true
+
+if [[ ! -s "$PCAP" ]]; then
+  echo "!!! No packets captured. Is HWM connected and streaming?"
+  exit 2
+fi
+
+echo
+echo ">>> pcap size: $(wc -c < "$PCAP") bytes"
+
+echo
+echo ">>> Extracting first 576-byte UDP payload"
+STICK_IP="$STICK_IP" STICK_PORT="$STICK_PORT" \
+  node tools/extract-frame.mjs "$PCAP" "$FRAME"
+
+echo
+echo ">>> Running try-hardcoded-key.mjs against the captured frame"
+node tools/try-hardcoded-key.mjs "$FRAME"

package/tools/capture-handshake.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Capture a COMPLETE HWM<->Stick session: TCP/2431 (control + handshake) +
+# UDP/2431 (encrypted DMX stream). We need the handshake from the very first
+# byte, so HWM should be DISCONNECTED from the Stick before running this.
+#
+# Workflow:
+#   1. In HWM: disconnect from the Stick (Network panel -> Disconnect).
+#   2. Run this script. It captures for 20 sec.
+#   3. While it's capturing: in HWM click Connect.
+#   4. Wait for HWM to reach "Connected" state, then move a fader so DMX
+#      starts streaming. Script should record both the TCP handshake AND
+#      a few UDP DMX frames.
+#
+# Output: /tmp/stick-handshake.pcap (timestamped copy at ./tools/captures/<ts>.pcap)
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+IFACE="${IFACE:-en0}"
+STICK_IP="${STICK_IP:-192.168.96.2}"
+DUR="${DUR:-60}"
+PCAP=/tmp/stick-handshake.pcap
+
+mkdir -p tools/captures
+TS=$(date +%Y%m%d-%H%M%S)
+SAVE="tools/captures/handshake-${TS}.pcap"
+
+echo ">>> About to capture ${DUR}s of ALL traffic to/from ${STICK_IP} on ${IFACE}"
+echo ">>> "
+echo ">>> BEFORE this starts: disconnect HWM from the Stick."
+echo ">>> AS SOON as the capture starts: click HWM Connect, then once"
+echo ">>> connected, move a fader to start DMX streaming."
+echo ">>> "
+read -p "Ready? (y/Enter to start, anything else to abort): " ans
+[[ -z "$ans" || "$ans" == "y" || "$ans" == "Y" ]] || { echo "aborted"; exit 1; }
+
+echo ">>> Capturing..."
+sudo tcpdump -i "$IFACE" -w "$PCAP" -G "$DUR" -W 1 \
+  "host ${STICK_IP}" \
+  2>/dev/null || true
+
+echo
+echo ">>> pcap size: $(wc -c < "$PCAP") bytes"
+cp "$PCAP" "$SAVE"
+echo ">>> archived to $SAVE"
+
+echo
+echo ">>> Packet summary (TCP control + UDP DMX)"
+node tools/dump-pcap-summary.mjs "$PCAP" > /tmp/stick-handshake-summary.txt
+echo "   written to /tmp/stick-handshake-summary.txt   ($(wc -l < /tmp/stick-handshake-summary.txt) packets)"
+echo
+echo ">>> First few TCP frames (the handshake):"
+grep ' TCP ' /tmp/stick-handshake-summary.txt | head -10
+echo
+echo ">>> First UDP DMX frame's first 32B (clear header):"
+grep ' UDP .* 576B' /tmp/stick-handshake-summary.txt | head -1
+echo
+echo ">>> Full summary at /tmp/stick-handshake-summary.txt"
+echo ">>> pcap at $SAVE — share this output and we'll decode the handshake"

package/tools/capture-send.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Capture a send_dmx run: all TCP + UDP traffic to/from the Stick while
+# send_dmx connects, handshakes and streams. The resulting pcap shows whether
+# the Stick accepts our handshake, whether our UDP DMX frames go out, and
+# whether the Stick errors or drops the connection.
+#
+#   ./tools/capture-send.sh <ip> <universe,channel=value> [...]
+#   e.g.  ./tools/capture-send.sh 192.168.96.2 0,6=255 0,9=255 0,10=170
+#
+# Needs sudo for tcpdump (it will prompt). Output: /tmp/send_dmx-run.pcap
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+IFACE="${IFACE:-en0}"
+IP="${1:?usage: capture-send.sh <ip> <universe,channel=value>...}"
+shift
+PCAP=/tmp/send_dmx-run.pcap
+rm -f "$PCAP"
+
+echo ">>> starting tcpdump (sudo) on ${IFACE}, host ${IP}"
+sudo tcpdump -i "$IFACE" -w "$PCAP" "host ${IP}" >/dev/null 2>&1 &
+sleep 3   # let tcpdump come up
+
+echo ">>> running: send_dmx ${IP} $*"
+node tools/send_dmx.mjs "$IP" "$@" || true
+sleep 2   # let the last frames + any Stick response land
+
+echo ">>> stopping tcpdump"
+sudo pkill -INT -f 'tcpdump.*send_dmx-run' 2>/dev/null || true
+sleep 1
+
+echo
+echo ">>> pcap: ${PCAP}  ($(wc -c < "$PCAP" 2>/dev/null || echo 0) bytes)"
+if [[ -s "$PCAP" ]]; then
+  node tools/dump-pcap-summary.mjs "$PCAP" 2>/dev/null | head -50 || true
+  echo ">>> total packets: $(node tools/dump-pcap-summary.mjs "$PCAP" 2>/dev/null | wc -l)"
+fi
+echo ">>> done — tell the assistant; ${PCAP} will be analysed."

package/tools/crack-kdf.mjs

@@ -0,0 +1,121 @@
+// Crack the key-derivation function: secret -> 32-byte AES-256 key.
+//
+// The AES key is KDF(ECDH shared secret). The cipher object stores a 32-byte
+// block A||B at cipher_obj+0x28, right before the key at +0x48 — likely the
+// shared secret kept resident. This slides a 32-byte "secret" window over all
+// captured memory blobs and tries a battery of KDFs against the known key.
+// If any KDF(window) == key, the derivation (and the secret's location) is
+// found — and the plugin can replicate it with no further RE.
+//
+// Usage:
+//   node tools/crack-kdf.mjs [key-hex] [blob.bin ...]
+//   key   defaults to the Path C recovered key
+//   blobs default to /tmp/stick-pathC-blob-*.bin
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+
+const DEFAULT_KEY =
+  '531e1b9f097be5de5785f5bf86473da34839fabb76676e95c0e4b808b42f8ac0';
+// hardcoded 33-byte secret deobfuscated from the binary (memory note)
+const HC = Buffer.from(
+  '527a5b46c56f3a5e670b4f0e338727d9' +
+  '4737ec0fc4af0dba93a51d93965191d0' + '8f', 'hex');
+
+let [, , maybeKey, ...blobArgs] = process.argv;
+let keyHex = DEFAULT_KEY;
+if (maybeKey && /^[0-9a-fA-F]{64}$/.test(maybeKey)) keyHex = maybeKey;
+else if (maybeKey) blobArgs.unshift(maybeKey);
+const KEY = Buffer.from(keyHex, 'hex');
+
+let blobs = blobArgs;
+if (blobs.length === 0) {
+  blobs = fs.readdirSync('/tmp')
+    .filter(f => /^stick-pathC-blob-.*\.bin$/.test(f))
+    .map(f => '/tmp/' + f);
+}
+if (blobs.length === 0) { console.error('no blobs found'); process.exit(1); }
+
+const sha256 = b => crypto.createHash('sha256').update(b).digest();
+const sha512 = b => crypto.createHash('sha512').update(b).digest();
+const sha1   = b => crypto.createHash('sha1').update(b).digest();
+const md5    = b => crypto.createHash('md5').update(b).digest();
+const blake2b = b => crypto.createHash('blake2b512').update(b).digest();
+const blake2s = b => crypto.createHash('blake2s256').update(b).digest();
+const hmac = (k, m) => crypto.createHmac('sha256', k).update(m).digest();
+const cat = (...xs) => Buffer.concat(xs);
+const rev = b => Buffer.from(b).reverse();
+const xor = (a, b) => { const o = Buffer.alloc(32); for (let i = 0; i < 32; i++) o[i] = a[i % a.length] ^ b[i % b.length]; return o; };
+function ecb(keyB, data) {
+  const c = crypto.createCipheriv('aes-256-ecb', keyB, null);
+  c.setAutoPadding(false);
+  return Buffer.concat([c.update(data), c.final()]);
+}
+
+const HC32 = HC.subarray(0, 32);
+const HC16a = HC.subarray(0, 16);
+const HC16b = HC.subarray(16, 32);
+
+// each KDF maps a candidate secret W (32 bytes) -> a 32-byte key
+const KDFS = [
+  ['identity',              W => W],
+  ['sha256(W)',             W => sha256(W)],
+  ['sha256(sha256(W))',     W => sha256(sha256(W))],
+  ['sha512(W)[:32]',        W => sha512(W).subarray(0, 32)],
+  ['blake2b(W)[:32]',       W => blake2b(W).subarray(0, 32)],
+  ['blake2s(W)',            W => blake2s(W)],
+  ['md5(W)|md5(revW)',      W => cat(md5(W), md5(rev(W)))],
+  ['sha256(W|HC33)',        W => sha256(cat(W, HC))],
+  ['sha256(HC33|W)',        W => sha256(cat(HC, W))],
+  ['sha256(W|HC32)',        W => sha256(cat(W, HC32))],
+  ['sha256(HC32|W)',        W => sha256(cat(HC32, W))],
+  ['sha512(W|HC33)[:32]',   W => sha512(cat(W, HC)).subarray(0, 32)],
+  ['sha512(HC33|W)[:32]',   W => sha512(cat(HC, W)).subarray(0, 32)],
+  ['hmac(HC33,W)',          W => hmac(HC, W)],
+  ['hmac(W,HC33)',          W => hmac(W, HC)],
+  ['hmac(HC32,W)',          W => hmac(HC32, W)],
+  ['hmac(W,HC32)',          W => hmac(W, HC32)],
+  ['hmac(W,W)',             W => hmac(W, W)],
+  ['W xor HC32',            W => xor(W, HC32)],
+  ['sha256(W xor HC32)',    W => sha256(xor(W, HC32))],
+  ['sha256(W|W)',           W => sha256(cat(W, W))],
+  ['aes256ecb(HC32,W)',     W => ecb(HC32, W)],
+  ['aes256ecb(W,HC32)',     W => ecb(W, HC32)],
+  ['sha256(W|HC16a)',       W => sha256(cat(W, HC16a))],
+  ['sha256(W|HC16b)',       W => sha256(cat(W, HC16b))],
+  ['sha256(sha1(W)|sha1(HC32))', W => sha256(cat(sha1(W), sha1(HC32)))],
+];
+
+const want = KEY.toString('hex');
+let tried = 0, hit = false;
+
+for (const path of blobs) {
+  let buf;
+  try { buf = fs.readFileSync(path); } catch { continue; }
+  const name = path.split('/').pop();
+  for (let o = 0; o + 32 <= buf.length; o++) {
+    const W = buf.subarray(o, o + 32);
+    for (const [kname, fn] of KDFS) {
+      tried++;
+      let out;
+      try { out = fn(W); } catch { continue; }
+      if (out && out.length >= 32 && out.subarray(0, 32).toString('hex') === want) {
+        hit = true;
+        console.log(`\n*** KDF MATCH ***`);
+        console.log(`  key      = ${want}`);
+        console.log(`  KDF      = ${kname}`);
+        console.log(`  secret W = ${W.toString('hex')}`);
+        console.log(`  location = ${name} + 0x${o.toString(16)}`);
+      }
+    }
+  }
+}
+
+console.log(`\ntried ${tried} (window, KDF) combinations across ${blobs.length} blob(s)`);
+if (!hit) {
+  console.log('no KDF in the battery maps any 32-byte window to the key.');
+  console.log('Next: capture a handshake + memory dump in one session, recover');
+  console.log('client_priv, compute the real X25519 shared secret, and either');
+  console.log('extend this battery or trace the KDF function directly.');
+  process.exit(3);
+}

package/tools/crack-key.mjs

@@ -0,0 +1,170 @@
+// Path A, final step — brute-force the AES key out of a saved cipher-object
+// dump by testing every window against a captured 576-byte DMX frame.
+//
+// The lldb scan (lldb_pathA_scan.py) saved the cipher object to
+// /tmp/stick-pathA-obj-*.bin. The raw key is somewhere in there, but the
+// exact offset / length / mode / byte order are uncertain. So: slide a
+// window over the whole dump, try it as an AES key in every common mode,
+// and score the decrypted DMX payload (DMX = mostly-zero bytes).
+//
+// Modes and what the IV does:
+//   ecb           - no IV; every block independent
+//   cbc/cfb/cfb8  - IV only affects the first block(s); blocks 1..33 (528
+//                   bytes) decrypt from the key alone -> scored IV-free
+//   ofb/ctr       - keystream depends on key AND the nonce/counter, every
+//                   block -> we try several nonce-derived 16-byte IVs
+//
+// Usage:
+//   node tools/crack-key.mjs <frame.bin> [objdump.bin ...]
+//   (objdumps default to /tmp/stick-pathA-obj-*.bin)
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+
+let [, , framePath, ...objPaths] = process.argv;
+if (!framePath) {
+  console.error('usage: node tools/crack-key.mjs <frame.bin> [objdump.bin ...]');
+  process.exit(1);
+}
+if (objPaths.length === 0) {
+  objPaths = fs.readdirSync('/tmp')
+    .filter(f => /^stick-pathA-obj-.*\.bin$/.test(f))
+    .map(f => '/tmp/' + f);
+  if (objPaths.length === 0) {
+    console.error('no /tmp/stick-pathA-obj-*.bin found — pass dumps explicitly');
+    process.exit(1);
+  }
+}
+
+const frame = fs.readFileSync(framePath);
+if (frame.length !== 576) {
+  console.error(`frame must be 576 bytes, got ${frame.length}`);
+  process.exit(1);
+}
+const header = frame.subarray(0, 0x20);
+const body   = frame.subarray(0x20, 0x240);        // 544 bytes, 34 AES blocks
+const nonce  = Buffer.from(header.subarray(0x18, 0x20));   // 8 bytes
+
+// candidate 16-byte IV / initial-counter blocks built from the clear header
+const z8 = Buffer.alloc(8);
+const ivCandidates = [
+  ['nonce|0',   Buffer.concat([nonce, z8])],
+  ['0|nonce',   Buffer.concat([z8, nonce])],
+  ['nonce|nonce', Buffer.concat([nonce, nonce])],
+  ['nonce|0..1', Buffer.concat([nonce, Buffer.from('0000000000000001', 'hex')])],
+  ['hdr[0:16]', Buffer.from(header.subarray(0, 16))],
+  ['hdr[16:32]', Buffer.from(header.subarray(16, 32))],
+  ['zero',      Buffer.alloc(16)],
+];
+const ZERO_IV = Buffer.alloc(16);
+
+// score a region of the plaintext: fraction of zero bytes
+function zeroRatio(out, from) {
+  let zeros = 0;
+  for (let i = from; i < out.length; i++) if (out[i] === 0) zeros++;
+  return zeros / (out.length - from);
+}
+
+function wordswap(buf) {
+  const o = Buffer.from(buf);
+  for (let i = 0; i + 4 <= o.length; i += 4) {
+    const a = o[i], b = o[i + 1], c = o[i + 2], d = o[i + 3];
+    o[i] = d; o[i + 1] = c; o[i + 2] = b; o[i + 3] = a;
+  }
+  return o;
+}
+
+function tryDecrypt(algo, key, iv) {
+  const d = iv === null
+    ? crypto.createDecipheriv(algo, key, null)
+    : crypto.createDecipheriv(algo, key, iv);
+  d.setAutoPadding(false);
+  return Buffer.concat([d.update(body), d.final()]);
+}
+
+const results = [];
+let tried = 0;
+
+for (const objPath of objPaths) {
+  const buf = fs.readFileSync(objPath);
+  const objName = objPath.split('/').pop();
+  for (const keylen of [16, 24, 32]) {
+    const bits = keylen * 8;
+    for (let off = 0; off + keylen <= buf.length; off++) {
+      const window = buf.subarray(off, off + keylen);
+      for (const [formName, keyBuf] of [['asis', window], ['wswap', wordswap(window)]]) {
+        const note = (extra) => ({ obj: objName, off, keylen, form: formName,
+          key: Buffer.from(keyBuf).toString('hex'), ...extra });
+
+        // --- ECB: no IV, score everything --------------------------------
+        try { tried++;
+          const out = tryDecrypt(`aes-${bits}-ecb`, keyBuf, null);
+          const z = zeroRatio(out, 0);
+          if (z > 0.55) results.push(note({ mode: 'ecb', iv: '-', z,
+            sample: out.subarray(0, 32).toString('hex') }));
+        } catch { /* skip */ }
+
+        // --- CBC / CFB / CFB8: IV-free score of blocks 1.. --------------
+        for (const mode of ['cbc', 'cfb', 'cfb8']) {
+          try { tried++;
+            const out = tryDecrypt(`aes-${bits}-${mode}`, keyBuf, ZERO_IV);
+            const z = zeroRatio(out, 16);
+            if (z > 0.55) results.push(note({ mode, iv: 'n/a(blk1+)', z,
+              sample: out.subarray(16, 48).toString('hex') }));
+          } catch { /* skip */ }
+        }
+
+        // --- OFB / CTR: keystream depends on the nonce ------------------
+        for (const mode of ['ofb', 'ctr']) {
+          for (const [ivName, iv] of ivCandidates) {
+            try { tried++;
+              const out = tryDecrypt(`aes-${bits}-${mode}`, keyBuf, iv);
+              const z = zeroRatio(out, 0);
+              if (z > 0.55) results.push(note({ mode, iv: ivName, z,
+                sample: out.subarray(0, 32).toString('hex') }));
+            } catch { /* skip */ }
+          }
+        }
+      }
+    }
+  }
+}
+
+console.log(`tried ${tried} (key,mode,iv,order) combinations`);
+console.log(`frame: seq=${frame[0x17]} nonce=${nonce.toString('hex')}`);
+console.log();
+
+results.sort((a, b) => b.z - a.z);
+if (results.length === 0) {
+  console.log('❌ nothing decrypted to DMX-shaped plaintext under any of:');
+  console.log('   ecb / cbc / cfb / cfb8 / ofb / ctr  (aes-128/192/256, both byte orders).');
+  console.log('   The key is not a byte-contiguous window of the cipher object,');
+  console.log('   OR it is derived (KDF) from the object bytes before use,');
+  console.log('   OR the block cipher is non-standard. Next: capture a 2nd frame');
+  console.log('   for a keystream diff, or Path C (patch the encrypt fn to log $rdi).');
+  process.exit(3);
+}
+
+console.log(`top ${Math.min(15, results.length)} candidates (zero-ratio):`);
+for (const r of results.slice(0, 15)) {
+  const pct = (r.z * 100).toFixed(1);
+  const flag = r.z > 0.80 ? '  <<< KEY FOUND' : '';
+  console.log(`  ${pct}%  aes-${r.keylen * 8}-${r.mode} iv=${r.iv} ${r.form}` +
+              `  ${r.obj}+0x${r.off.toString(16)}${flag}`);
+  console.log(`        key=${r.key}`);
+  console.log(`        plaintext=${r.sample}`);
+}
+
+const best = results[0];
+console.log();
+if (best.z > 0.80) {
+  console.log('✅ KEY RECOVERED');
+  console.log(`   algorithm : aes-${best.keylen * 8}-${best.mode}` +
+              `  iv=${best.iv}  (byte order: ${best.form})`);
+  console.log(`   key       : ${best.key}`);
+  console.log(`   location  : ${best.obj} +0x${best.off.toString(16)}`);
+  process.exit(0);
+} else {
+  console.log('⚠️  best candidate is below the 80% confidence bar — inspect above.');
+  process.exit(2);
+}