@ecopoesis/homebridge-dmx 0.1.0

package/tools/lldb_pathD_kdf_watch.py

@@ -0,0 +1,281 @@
+"""
+Path D — catch the key-derivation function with a hardware watchpoint.
+
+The 32-byte AES key lives at cipher_obj+0x48 and is rewritten when the
+TCP/2431 handshake completes. cipher_obj is a stable heap address (reused
+across reconnects within one HWM run). So: arm a write-watchpoint on
+cipher_obj+0x48, let the user reconnect HWM, and the instant the handshake
+writes the freshly-derived key, lldb stops — with the KDF call chain on the
+backtrace and the ECDH shared secret live in registers/stack.
+
+lldb's SBWatchpoint has no script callback, so run-control is driven here:
+arm the watchpoint(s), then loop process.Continue() until a watched key
+slot CHANGES to a new non-zero value (the KDF rederive — not the disconnect
+zeroing, not a spurious same-value write).
+
+Usage (driven by tools/pathD-kdf-watch.sh):
+  lldb -p <PID> --batch \
+       -o "command script import tools/lldb_pathD_kdf_watch.py" \
+       -o "detach" -o "quit"
+After it prints "watchpoint(s) armed", reconnect HWM to the Stick.
+"""
+
+import os
+import sys
+import struct
+import time
+
+try:
+    import lldb
+except ImportError:
+    lldb = None
+
+CIPHER_VPTR_FILEADDR = 0x10095F838
+KEY_OFF = 0x48
+LOG_PATH = "/tmp/stick-pathD-kdf.log"
+MAX_CONTINUES = 400
+
+_logf = None
+_blobs = []
+
+
+def log(m=""):
+    print(m)
+    sys.stdout.flush()
+    if _logf:
+        _logf.write(m + "\n")
+        _logf.flush()
+
+
+def hexs(b):
+    return "".join("%02x" % x for x in b)
+
+
+def read_mem(process, addr, size):
+    err = lldb.SBError()
+    d = process.ReadMemory(addr, size, err)
+    return d if (err.Success() and d) else None
+
+
+def rw_regions(process):
+    regions = process.GetMemoryRegions()
+    for i in range(regions.GetSize()):
+        info = lldb.SBMemoryRegionInfo()
+        if regions.GetMemoryRegionAtIndex(i, info) \
+           and info.IsReadable() and info.IsWritable():
+            yield info.GetRegionBase(), info.GetRegionEnd()
+
+
+def find_cipher_objects(process, target):
+    mod = None
+    for m in target.module_iter():
+        if m.GetFileSpec().GetFilename() == "HardwareManager":
+            mod = m
+            break
+    if not mod:
+        return []
+    vptr = mod.ResolveFileAddress(CIPHER_VPTR_FILEADDR).GetLoadAddress(target)
+    if vptr == lldb.LLDB_INVALID_ADDRESS:
+        return []
+    pattern = struct.pack("<Q", vptr)
+    hits = []
+    CH = 8 * 1024 * 1024
+    for base, end in rw_regions(process):
+        if end - base > 4 * 1024 * 1024 * 1024:
+            continue
+        addr, carry = base, b""
+        while addr < end:
+            n = min(CH, end - addr)
+            data = read_mem(process, addr, n)
+            if data is None:
+                addr += n
+                carry = b""
+                continue
+            bb = carry + data
+            bbase = addr - len(carry)
+            s = 0
+            while True:
+                idx = bb.find(pattern, s)
+                if idx < 0:
+                    break
+                hits.append(bbase + idx)
+                s = idx + 1
+            carry = bb[-7:]
+            addr += n
+    return [h for h in hits if h > 0x7000_0000_0000]   # heap objects only
+
+
+def backtrace(thread):
+    log("")
+    log("backtrace (KDF call chain):")
+    for i in range(min(thread.GetNumFrames(), 28)):
+        f = thread.GetFrameAtIndex(i)
+        log("  #%-2d 0x%x  %s" % (i, f.GetPC(), f.GetFunctionName() or "?"))
+
+
+def capture(process, frame, label):
+    log("")
+    log("=" * 68)
+    log("CAPTURE @ %s" % label)
+    log("=" * 68)
+    regs = {}
+    for r in ("rdi rsi rdx rcx r8 r9 rax rbx rbp rsp r10 r11 r12 r13 r14 "
+              "r15 rip").split():
+        v = frame.FindRegister(r)
+        regs[r] = v.GetValueAsUnsigned() if v.IsValid() else 0
+        log("  %-4s = 0x%x" % (r, regs[r]))
+    for r in ("rdi rsi rdx rcx r8 r9 rax rbx r12 r13 r14 r15").split():
+        a = regs[r]
+        if 0x10000 < a < 0x7fffffffffff:
+            d = read_mem(process, a, 1024)
+            if d:
+                _blobs.append(("%s_0x%x" % (r, a), a, d))
+    rsp = regs["rsp"]
+    st = read_mem(process, rsp - 0x400, 0x6000)
+    if st:
+        _blobs.append(("stack_0x%x" % (rsp - 0x400), rsp - 0x400, st))
+
+
+def finalize():
+    log("")
+    log("=" * 68)
+    log("saving %d blob(s) for offline KDF analysis" % len(_blobs))
+    for label, addr, data in _blobs:
+        p = "/tmp/stick-pathD-blob-%s.bin" % label
+        with open(p, "wb") as f:
+            f.write(data)
+        log("  %-22s %6d B @ 0x%x" % (label, len(data), addr))
+    log("")
+    log("NEXT: node tools/crack-kdf.mjs <new-key-hex> /tmp/stick-pathD-blob-*.bin")
+    log("done — detaching. log: %s" % LOG_PATH)
+
+
+def __lldb_init_module(debugger, internal_dict):
+    global _logf
+    _logf = open(LOG_PATH, "w")
+    # async: process.Continue() returns immediately and we poll, so the
+    # script can never wedge in an unkillable synchronous kernel wait.
+    debugger.SetAsync(True)
+
+    target = debugger.GetSelectedTarget()
+    process = target.GetProcess() if target else None
+    if not process or not process.IsValid():
+        log("ERROR: no live process")
+        return
+
+    log("=== Path D KDF watchpoint  %s ===" % time.strftime("%Y-%m-%d %H:%M:%S"))
+    objs = find_cipher_objects(process, target)
+    if not objs:
+        log("ERROR: no live cipher object found")
+        return
+    log("cipher object(s): %s" % ", ".join("0x%x" % o for o in objs))
+
+    # The 32-byte key spans cipher_obj+0x48 (half C) .. +0x58 (half D). A real
+    # handshake rederive changes BOTH halves; UI writes touch only one. Watch
+    # both 8-byte halves so we get a hit once the full key is written. Active
+    # objects (non-zero key) come first so they get watchpoints within the
+    # hardware budget (4 on x86_64).
+    objs.sort(key=lambda o: 0 if any(read_mem(process, o + KEY_OFF, 32) or b"")
+              else 1)
+    # one initial 32-byte key per object
+    initials = {}
+    for o in objs:
+        initials[o] = read_mem(process, o + KEY_OFF, 32) or b"\x00" * 32
+        log("  obj 0x%x  key = %s" % (o, hexs(initials[o])))
+
+    budget = 4
+    armed_objs = []
+    for o in objs:
+        ok = False
+        for half in (0x48, 0x58):
+            if budget <= 0:
+                break
+            err = lldb.SBError()
+            wp = target.WatchAddress(o + half, 8, False, True, err)
+            if err.Success() and wp and wp.IsValid():
+                budget -= 1
+                ok = True
+                log("    watchpoint id %d on 0x%x (+0x%x)"
+                    % (wp.GetID(), o + half, half))
+            else:
+                log("    WARNING: watchpoint on 0x%x failed: %s"
+                    % (o + half, err))
+        if ok:
+            armed_objs.append(o)
+
+    if not armed_objs:
+        log("ERROR: no watchpoints armed")
+        return
+
+    # Force the reconnect ourselves: HWM is already stopped (from the lldb
+    # attach). Hold it stopped long enough that the Stick drops the idle
+    # TCP/2431 session (~41s sufficed in an earlier scan; 85s is safe). When
+    # we then resume, HWM finds the dead socket and reconnects — a fresh
+    # handshake + KDF — with no UI interaction needed.
+    FREEZE = 85
+    log("")
+    log(">>> watchpoint(s) armed.")
+    log(">>> Freezing HWM for %ds so the Stick drops the idle TCP session" % FREEZE)
+    log(">>> (HWM has been stopped since the lldb attach; just holding it).")
+    t0 = time.time()
+    while time.time() - t0 < FREEZE:
+        time.sleep(1.0)
+    log(">>> resuming HWM — it will detect the dead socket and reconnect.")
+    log(">>> watching for the reconnect handshake to rederive the key ...")
+    log("")
+
+    # Async poll loop, hard-bounded by a wall-clock deadline. process.Continue()
+    # returns immediately; we poll GetState() with short sleeps, so the script
+    # always self-terminates and lets lldb run `detach`/`quit` — it can never
+    # hang in an unkillable synchronous wait.
+    last_seen = dict(initials)        # last key value observed per object
+    deadline = time.time() + 300.0
+    process.Continue()
+
+    while time.time() < deadline:
+        st = process.GetState()
+        if st == lldb.eStateExited:
+            log("process exited — aborting")
+            return
+        if st != lldb.eStateStopped:
+            time.sleep(0.2)
+            continue
+
+        # stopped — a watchpoint (or signal) hit
+        thread = process.GetSelectedThread()
+        for t in process:
+            if t.GetStopReason() == lldb.eStopReasonWatchpoint:
+                thread = t
+                break
+
+        full = None
+        for o in armed_objs:
+            v = read_mem(process, o + KEY_OFF, 32)
+            if not v or v == last_seen[o]:
+                continue                      # unchanged / stale re-read
+            last_seen[o] = v
+            init = initials[o]
+            c_new = v[0:16] != init[0:16]
+            d_new = v[16:32] != init[16:32]
+            nonzero = any(b != 0 for b in v)
+            if c_new and d_new and nonzero:
+                full = (o, v)
+            else:
+                log("  (partial write: %s changed via %s — skipping)"
+                    % ("C" if c_new else "D" if d_new else "?",
+                       thread.GetFrameAtIndex(0).GetFunctionName() or "?"))
+        if full:
+            log("")
+            log(">>> FULL KEY REDERIVED — key@0x%x" % (full[0] + KEY_OFF))
+            log("    %s" % hexs(full[1]))
+            backtrace(thread)
+            capture(process, thread.GetFrameAtIndex(0), "full key rederive (KDF)")
+            finalize()
+            return
+
+        process.Continue()               # resume, wait for the next write
+        time.sleep(0.25)
+
+    log("")
+    log("timed out after 5 min — no full key rederive seen. HWM left running;")
+    log("re-run and be sure to fully Disconnect THEN Connect in HWM.")

package/tools/pathA-launch-hwm.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Path A, step 1 — launch a debuggable copy of the ESA2 Hardware Manager.
+#
+# Why a copy: the installed ESA2 HWM is signed with hardened runtime and NO
+# `get-task-allow`, so lldb cannot attach (`attach failed: lost connection`).
+# We copy it, adhoc-re-sign the whole bundle with tools/hwm-entitlements.plist
+# (which now includes `get-task-allow` + `disable-library-validation`), and
+# launch that. lldb can then attach to the copy for a passive memory scan.
+#
+# Source MUST be the ESA2 build — the Ghidra addresses (vptr 0x10095F838 etc.)
+# come from the 2024-03-21 ESA2 binary, not the EsaPro2 one.
+#
+# Usage:
+#   tools/pathA-launch-hwm.sh            # launch the debug copy
+#   FORCE_KILL=1 tools/pathA-launch-hwm.sh   # also kill any running HWM first
+#
+# The Stick is single-session: only one Hardware Manager can hold the TCP/2431
+# slot. Quit the normally-installed HWM before launching this copy.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC="/Applications/ESA2/HardwareManager/HardwareManager.app"
+COPY="/tmp/HM-ESA2-dbg.app"
+ENTS="$SCRIPT_DIR/hwm-entitlements.plist"
+
+[ -d "$SRC" ]  || { echo "ERROR: $SRC not found"; exit 1; }
+[ -f "$ENTS" ] || { echo "ERROR: $ENTS not found"; exit 1; }
+
+# --- single-session guard -------------------------------------------------
+RUNNING="$(pgrep -fl 'HardwareManager.app/Contents/MacOS/HardwareManager' || true)"
+if [ -n "$RUNNING" ]; then
+  # ignore our own debug copy when deciding
+  OTHER="$(echo "$RUNNING" | grep -v "$COPY" || true)"
+  if [ -n "$OTHER" ]; then
+    echo ">>> A Hardware Manager is already running:"
+    echo "$OTHER" | sed 's/^/      /'
+    if [ "${FORCE_KILL:-0}" = "1" ]; then
+      echo ">>> FORCE_KILL=1 — terminating it so the Stick session frees up."
+      echo "$OTHER" | awk '{print $1}' | xargs -r kill
+      sleep 2
+    else
+      echo ">>> The Stick allows only ONE HWM session. Quit it, then re-run."
+      echo ">>> (or re-run with FORCE_KILL=1)"
+      exit 2
+    fi
+  fi
+fi
+
+# --- (re)build the debug copy --------------------------------------------
+if [ "${REBUILD:-0}" = "1" ] && [ -d "$COPY" ]; then
+  echo ">>> REBUILD=1 — removing stale $COPY"
+  rm -rf "$COPY"
+fi
+
+if [ ! -d "$COPY" ]; then
+  echo ">>> Copying $SRC"
+  echo "    -> $COPY"
+  cp -R "$SRC" "$COPY"
+
+  echo ">>> Adhoc re-signing the bundle with debug entitlements"
+  # Adhoc (--sign -), no hardened runtime, no library validation. --deep
+  # re-signs the nested Qt frameworks adhoc too so signatures stay
+  # consistent. The entitlements (incl. get-task-allow) apply to the main
+  # executable — that is what lldb attaches to.
+  codesign --force --deep --sign - --entitlements "$ENTS" "$COPY" 2>&1 \
+    | sed 's/^/    /'
+
+  echo ">>> Verifying get-task-allow landed on the main executable"
+  if codesign -d --entitlements - "$COPY" 2>/dev/null | grep -q 'get-task-allow'; then
+    echo "    OK: get-task-allow present"
+  else
+    echo "    WARNING: get-task-allow not found — lldb attach may still fail"
+  fi
+else
+  echo ">>> Using existing debug copy at $COPY  (REBUILD=1 to recreate)"
+fi
+
+echo
+echo ">>> Launching the debug Hardware Manager"
+echo "    Next steps:"
+echo "      1. In this HWM, connect to the Stick at 192.168.96.2"
+echo "      2. Open the DMX / fader screen so live DMX is streaming"
+echo "      3. In another terminal:  tools/pathA-scan.sh"
+echo
+open -n "$COPY"

package/tools/pathA-scan.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Path A, step 2 — attach lldb to the debug HWM and run the passive scan.
+#
+# Prereqs:
+#   1. tools/pathA-launch-hwm.sh has launched the debug copy
+#   2. that HWM is connected to the Stick and streaming live DMX
+#
+# This attaches lldb, runs tools/lldb-pathA-scan.py (no breakpoints — one
+# brief stop while it scans), then detaches. HWM keeps running.
+#
+# Set STICK_HEAP_DUMP=1 to also dump rw memory for an offline heap-wide
+# AES key-schedule search (slower; only needed if the fast scan finds nothing).
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SCAN_PY="tools/lldb_pathA_scan.py"
+LOG="/tmp/stick-pathA-scan.log"
+
+# Find the debug copy's pid (NOT the installed HWM).
+PID="$(pgrep -f '/tmp/HM-ESA2-dbg.app/Contents/MacOS/HardwareManager' | head -1)"
+
+if [ -z "$PID" ]; then
+  echo "ERROR: debug HWM not running."
+  echo "  Run tools/pathA-launch-hwm.sh first, connect it to the Stick,"
+  echo "  and open the DMX screen so live DMX is streaming."
+  # show what IS running, to help diagnose
+  echo
+  echo "Currently running Hardware Managers:"
+  pgrep -fl 'HardwareManager.app/Contents/MacOS/HardwareManager' | sed 's/^/  /' \
+    || echo "  (none)"
+  exit 1
+fi
+
+echo ">>> debug HWM pid = $PID"
+echo ">>> attaching lldb for a passive scan (one brief stop, then detach)"
+[ "${STICK_HEAP_DUMP:-0}" = "1" ] && echo ">>> STICK_HEAP_DUMP=1 — will also dump rw memory"
+echo
+
+STICK_HEAP_DUMP="${STICK_HEAP_DUMP:-0}" \
+lldb --batch \
+  -o "command script import $SCAN_PY" \
+  -o "detach" \
+  -o "quit" \
+  -p "$PID" 2>&1 | sed 's/^/  /'
+
+echo
+if [ -f "$LOG" ]; then
+  echo ">>> full log saved at $LOG"
+else
+  echo "!!! no log produced — the scan script may have errored above"
+fi

package/tools/pathC-keytrace.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Path C-lite — attach lldb and run the runtime key-trace.
+#
+# Prereqs (same as pathA-scan.sh):
+#   - the debug HWM (tools/pathA-launch-hwm.sh) is running
+#   - it is connected to the Stick and streaming live DMX
+#
+# Sets one-shot breakpoints on the encrypt path, lets ONE frame hit, dumps
+# registers + stack + the cipher/device memory, runs the AES key-schedule
+# detector, then detaches. HWM is stopped ~1-2s total.
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SCAN_PY="tools/lldb_pathC_keytrace.py"
+LOG="/tmp/stick-pathC-keytrace.log"
+
+PID="$(pgrep -f '/tmp/HM-ESA2-dbg.app/Contents/MacOS/HardwareManager' | head -1)"
+if [ -z "$PID" ]; then
+  echo "ERROR: debug HWM not running. Run tools/pathA-launch-hwm.sh first,"
+  echo "       connect it to the Stick, and stream live DMX."
+  exit 1
+fi
+
+echo ">>> debug HWM pid = $PID"
+echo ">>> attaching lldb for the runtime key-trace"
+echo ">>> 'continue' runs until the encrypt path fires (~40ms at 25Hz)"
+echo
+
+# 'continue' blocks until a breakpoint callback returns True (stop). The
+# script's fallback (capture-at-entry after 6 frames) guarantees that always
+# happens, so 'continue' cannot hang. timeout is just a safety net.
+timeout 180 lldb --batch \
+  -o "command script import $SCAN_PY" \
+  -o "continue" \
+  -o "detach" \
+  -o "quit" \
+  -p "$PID" 2>&1 | sed 's/^/  /'
+
+echo
+if [ -f "$LOG" ]; then
+  echo ">>> full log: $LOG"
+  echo ">>> captured memory blobs: /tmp/stick-pathC-blob-*.bin"
+  echo
+  echo "If a key was recovered:  node tools/try-key.mjs <frame.bin> <key-hex>"
+  echo "Otherwise brute-force:   node tools/crack-key.mjs <frame.bin> /tmp/stick-pathC-blob-*.bin"
+else
+  echo "!!! no log produced — the trace script may have errored above"
+fi

package/tools/pathC-run.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Atomic same-session key capture.
+#
+# The Stick's AES key is per-session: every TCP/2431 reconnect derives a new
+# key. A long lldb stop (the 41s passive scan) kills the session, so the key
+# you read no longer matches frames captured afterwards.
+#
+# This script avoids that:
+#   1. start tcpdump in the background (captures encrypted frames)
+#   2. run the Path C breakpoint key-trace — its stop is only ~1-2s, short
+#      enough that the TCP session survives
+#   3. extract the FIRST captured frame (captured before the attach => same
+#      session as the key Path C caught)
+#   4. crack-key / try-key against the captured memory
+#
+# Run it from a terminal (tcpdump needs sudo — it will prompt once):
+#   tools/pathC-run.sh
+#
+# Prereqs: the debug HWM is running, connected to the Stick, streaming DMX.
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+IFACE="${IFACE:-en0}"
+STICK_IP="${STICK_IP:-192.168.96.2}"
+STICK_PORT="${STICK_PORT:-2431}"
+PCAP=/tmp/stick-pathC.pcap
+FRAME=/tmp/stick-pathC-frame.bin
+CAP_SECS="${CAP_SECS:-55}"
+
+echo ">>> caching sudo credentials for tcpdump"
+sudo -v
+
+echo ">>> starting ${CAP_SECS}s background capture of UDP -> ${STICK_IP}:${STICK_PORT} on ${IFACE}"
+rm -f "$PCAP" "$FRAME"
+sudo tcpdump -i "$IFACE" -w "$PCAP" -G "$CAP_SECS" -W 1 \
+  "udp and host ${STICK_IP} and port ${STICK_PORT}" 2>/dev/null &
+TCPDUMP_PID=$!
+sleep 3      # let some frames land before we attach
+
+echo ">>> running Path C key-trace (short stop — session should survive)"
+tools/pathC-keytrace.sh
+
+echo ">>> waiting for the background capture to finish"
+wait "$TCPDUMP_PID" 2>/dev/null || true
+
+if [[ ! -s "$PCAP" ]]; then
+  echo "!!! no packets captured — is HWM connected + streaming? wrong IFACE?"
+  exit 2
+fi
+echo ">>> pcap: $(wc -c < "$PCAP") bytes"
+
+echo ">>> extracting the first 576-byte frame (pre-attach => same session)"
+STICK_IP="$STICK_IP" STICK_PORT="$STICK_PORT" \
+  node tools/extract-frame.mjs "$PCAP" "$FRAME" || {
+    echo "!!! no 576-byte frame found in the capture"; exit 3; }
+
+echo
+echo ">>> === try any key Path C recovered from a live schedule ==="
+shopt -s nullglob
+KEYHIT=0
+for kf in /tmp/stick-pathC-key-*.bin; do
+  KEYHIT=1
+  echo "--- $kf ---"
+  node tools/try-key.mjs "$FRAME" "$(xxd -p -c256 "$kf")" || true
+done
+[ "$KEYHIT" = 0 ] && echo "(Path C recovered no standard schedule — going to brute-force)"
+
+echo
+echo ">>> === brute-force the captured memory blobs against the frame ==="
+node tools/crack-key.mjs "$FRAME" /tmp/stick-pathC-blob-*.bin

package/tools/pathD-kdf-watch.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Path D — attach lldb, arm a watchpoint on the AES key, catch the KDF.
+#
+# Prereqs: the debug HWM is running and currently CONNECTED to the Stick
+# (so the cipher object exists with a live key to watch).
+#
+# Flow:
+#   1. this attaches lldb and arms a write-watchpoint on cipher_obj+0x48
+#   2. when it prints "watchpoint armed", YOU disconnect HWM from the Stick
+#      and reconnect it (Network panel -> Disconnect, then Connect)
+#   3. the handshake rederives the key -> watchpoint fires -> lldb dumps the
+#      KDF backtrace + registers + stack, then detaches
+#
+# Also run a handshake capture in another terminal so the X25519 pubkeys
+# are recorded for the same session:
+#   tools/capture-handshake.sh
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SCAN_PY="tools/lldb_pathD_kdf_watch.py"
+LOG="/tmp/stick-pathD-kdf.log"
+
+PID="$(pgrep -f '/tmp/HM-ESA2-dbg.app/Contents/MacOS/HardwareManager' | head -1)"
+if [ -z "$PID" ]; then
+  echo "ERROR: debug HWM not running — run tools/pathA-launch-hwm.sh first."
+  exit 1
+fi
+
+echo ">>> debug HWM pid = $PID"
+echo ">>> attaching lldb and arming the KDF watchpoint"
+echo ">>> when it says 'watchpoint armed', reconnect HWM to the Stick"
+echo
+
+# The import script arms the watchpoint and drives its own continue-loop
+# (lldb watchpoints have no script callback), so there is NO -o "continue"
+# here. Generous timeout: it waits for a human-driven reconnect.
+timeout 600 lldb --batch \
+  -o "command script import $SCAN_PY" \
+  -o "detach" \
+  -o "quit" \
+  -p "$PID" 2>&1 | sed 's/^/  /'
+
+echo
+if [ -f "$LOG" ]; then
+  echo ">>> full log: $LOG"
+  echo ">>> captured blobs: /tmp/stick-pathD-blob-*.bin"
+  echo ">>> then: node tools/crack-kdf.mjs <new-key-hex> /tmp/stick-pathD-blob-*.bin"
+else
+  echo "!!! no log produced — the trace script may have errored above"
+fi

package/tools/quick-trigger.mjs

@@ -0,0 +1,86 @@
+// Stick-DE3 "Quick Trigger" tester — documented, UNencrypted, UNauthenticated
+// control path (STICK Remote Protocol spec, section 1).
+//
+// Sends a 24-byte Quick Trigger packet via UDP to the Stick on port 2430.
+// Per the spec, UDP/2430 Quick Triggering "has no authentication layer" — so
+// this works regardless of firmware 2.x TCP auth / "Security for Cloud Access".
+//
+// Packet layout (exact, from the spec; example in the spec sums to 24 bytes):
+//   [0..7]  ID[8]      "Stick_3A"
+//   [8..9]  OpCode[2]  109  -> 0x6D 0x00  (LE)
+//   [10..11]SceneNr[2] LE   (Scene Number = Page*50 + SceneInPage)
+//   [12]    ZoneSyncId 1
+//   [13]    Command    1    (see CMD below)
+//   [14..15]Dimmer[2]  LE
+//   [16..17]Speed[2]   LE
+//   [18]    Unused     1
+//   [19]    Unused     1
+//   [20..23]Color[4]   R G B 00
+//
+// Usage:
+//   node tools/quick-trigger.mjs blackout-on
+//   node tools/quick-trigger.mjs blackout-off
+//   node tools/quick-trigger.mjs scene-on  <sceneNr>
+//   node tools/quick-trigger.mjs scene-off <sceneNr>
+//   node tools/quick-trigger.mjs dimmer <sceneNr> <0-255>
+//   node tools/quick-trigger.mjs color  <sceneNr> <r> <g> <b>
+//   node tools/quick-trigger.mjs raw    <sceneNr> <cmd> [dimmer] [r] [g] [b]
+// Env: STICK_IP (default 192.168.96.2), STICK_PORT (default 2430)
+
+import dgram from 'node:dgram';
+
+const STICK_IP   = process.env.STICK_IP   || '192.168.96.2';
+const STICK_PORT = Number(process.env.STICK_PORT || 2430);
+
+const CMD = {
+  'scene-off': 0, 'scene-on': 1, 'pause-off': 2, 'pause-on': 3,
+  'reset': 4, 'dimmer-set': 5, 'speed-set': 6, 'color-set': 7,
+  'blackout-off': 8, 'blackout-on': 9,
+};
+
+function buildPacket({ scene = 0, zoneSync = 0, command = 0, dimmer = 0, speed = 0, r = 0, g = 0, b = 0 }) {
+  const p = Buffer.alloc(24);
+  p.write('Stick_3A', 0, 'latin1'); // [0..7]
+  p.writeUInt16LE(109, 8);          // [8..9]  OpCode
+  p.writeUInt16LE(scene & 0xffff, 10); // [10..11] SceneNr
+  p.writeUInt8(zoneSync & 0xff, 12);   // [12]
+  p.writeUInt8(command & 0xff, 13);    // [13] Command
+  p.writeUInt16LE(dimmer & 0xffff, 14);// [14..15] Dimmer
+  p.writeUInt16LE(speed & 0xffff, 16); // [16..17] Speed
+  // [18],[19] unused = 0
+  p.writeUInt8(r & 0xff, 20);
+  p.writeUInt8(g & 0xff, 21);
+  p.writeUInt8(b & 0xff, 22);
+  // [23] = 0
+  return p;
+}
+
+const [sub, ...rest] = process.argv.slice(2);
+if (!sub) {
+  console.error('usage: node tools/quick-trigger.mjs <blackout-on|blackout-off|scene-on|scene-off|dimmer|color|raw> [args]');
+  process.exit(1);
+}
+
+let opts;
+switch (sub) {
+  case 'blackout-on':  opts = { command: CMD['blackout-on'] }; break;
+  case 'blackout-off': opts = { command: CMD['blackout-off'] }; break;
+  case 'scene-on':     opts = { command: CMD['scene-on'],  scene: +rest[0] }; break;
+  case 'scene-off':    opts = { command: CMD['scene-off'], scene: +rest[0] }; break;
+  case 'dimmer':       opts = { command: CMD['dimmer-set'], scene: +rest[0], dimmer: +rest[1] }; break;
+  case 'color':        opts = { command: CMD['color-set'],  scene: +rest[0], r: +rest[1], g: +rest[2], b: +rest[3] }; break;
+  case 'raw':          opts = { scene: +rest[0], command: +rest[1], dimmer: +(rest[2]||0), r: +(rest[3]||0), g: +(rest[4]||0), b: +(rest[5]||0) }; break;
+  default:
+    console.error(`unknown subcommand: ${sub}`);
+    process.exit(1);
+}
+
+const pkt = buildPacket(opts);
+const sock = dgram.createSocket('udp4');
+const ts = new Date().toISOString();
+sock.send(pkt, STICK_PORT, STICK_IP, (err) => {
+  if (err) { console.error(`${ts}  send error:`, err.message); process.exit(1); }
+  console.log(`${ts}  -> ${STICK_IP}:${STICK_PORT}  ${sub} ${rest.join(' ')}`);
+  console.log(`  ${pkt.length}B: ${pkt.toString('hex').replace(/(..)/g, '$1 ').trim()}`);
+  sock.close();
+});