signalk-telltale-plugin 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# signalk-telltale-plugin
+
+**Telltale Uplink** — a [Signal K](https://signalk.org/) server plugin that streams a
+decimated, disk-buffered copy of your boat's data to a self-hosted *shore* collector
+over HTTPS, with an HMAC-signed command channel back to the boat. It also supports
+bounded **raw NMEA 2000 capture**, switch **discovery**, and gated **digital-switching
+actuation** — a "universal remote" for your CZone/N2K loads.
+
+Part of the [Telltale](https://gitlab.dupuis.xyz/andrewdupuis/telltale) project (boat
+plugin + shore stack: collector, public portal, Grafana, TimescaleDB).
+
+## What it does
+
+- **Telemetry uplink** — samples a path allowlist on an interval, batches snapshots,
+  and POSTs them to the shore collector. A bounded, flash-friendly disk queue survives
+  reboots and drains only on ack, so a flaky cellular link never loses or duplicates
+  data and never fills the Cerbo's `/data` partition.
+- **Command channel** — every POST may return an HMAC-signed directive: change the
+  sample/post intervals (declarative + versioned) or run a one-shot command
+  (e.g. `flushBuffer`). Signatures are verified with a shared `commandKey` before
+  anything is applied; a bad signature is ignored.
+- **Raw N2K capture** — a shore-initiated, time-boxed, rate-limited window taps the
+  canboat-parsed N2K stream (`N2KAnalyzerOut`) and ships `{pgn, src, dst, fields}`
+  frames for remote viewing. Auto-expires so cellular usage stays sane.
+- **Discovery (Phase 1, read-only)** — name a load, flip its physical switch a few
+  times, and the plugin edge-correlates the switching PGNs to infer the
+  `(pgn, instance, switch)` signature, with confidence + co-moving ambiguities.
+- **Digital-switching actuation (gated)** — send 127502 / 126208 to switch a load,
+  with read-back confirmation — behind a layered safety model (see below).
+
+## Install
+
+In the Signal K admin UI: **Appstore → Available → search "telltale" → Install**,
+then restart. No SSH/root required. (Or `npm install signalk-telltale-plugin` in your
+server's data directory.)
+
+Then **Server → Plugin Config → Telltale Uplink**, enable it, and set:
+
+| Setting | Notes |
+|---|---|
+| **Shore collector URL** | e.g. `https://your-shore/api/ingest` |
+| **Vessel id** | the `source` your shore expects (e.g. `goblin`) |
+| **Ingest token** | bearer that proves the boat may write (matches shore `INGEST_TOKEN`) |
+| **Command key** | shared secret that signs/verifies directives (matches shore `COMMAND_KEY`) |
+| **Sample / post interval (ms)** | default 15000 each |
+| **Paths to send** | empty = a sensible nav/wind/depth/battery default |
+| **Enable actuation** | master arm — **leave OFF** unless actively switching loads |
+| **Switching allowlist** | the boat-side list of confirmed, actuatable targets |
+
+## Actuation safety model
+
+Actuation is **off by default** and gated by more than the HMAC:
+
+1. **The boat-side allowlist is the real control.** The plugin only emits commands
+   matching a locally-configured, `confirmed`, non-`excluded` target. A compromised or
+   buggy shore cannot address anything you haven't explicitly enabled on the boat.
+2. **Master arm toggle, default OFF.** Telemetry, raw capture, and discovery always
+   work; actuation is ignored entirely unless armed.
+3. **TTL on commands.** Stale actuation commands are dropped, never executed late after
+   a buffered outage.
+4. **Closed-loop confirm.** A target is only `confirmed` after a Phase-2 test toggles it
+   and reads back the resulting 127501 status; only confirmed targets are actuatable.
+5. **Hard exclusions.** Never allowlist loads where a wrong/stale/spoofed state could
+   endanger the boat (bilge pumps, nav/steaming lights underway, engine, windlass,
+   anything affecting watertight integrity). Cabin lights, fans, fridge: fine.
+
+> Actuation requires Signal K's **writable canboatjs** N2K connection (sends to
+> NMEA 2000). Raw capture and discovery work with any N2K input.
+
+## Development
+
+```bash
+npm test        # node:test unit suite (hmac, buffer, discovery, actuation, n2k)
+```
+
+Local edit-in-place loop, the shore stack, and the offline simulators are documented
+in the [project INSTRUCTIONS](https://gitlab.dupuis.xyz/andrewdupuis/telltale).
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,393 @@
+'use strict';
+const path = require('path');
+const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+const { DiskQueue } = require('./lib/buffer');
+const { verify } = require('./lib/hmac');
+const { tapN2K, createSender } = require('./lib/n2k');
+const { Correlator, instanceOf } = require('./lib/discovery');
+const actuation = require('./lib/actuation');
+
+const DEFAULT_PATHS = [
+  'navigation.position',
+  'navigation.speedOverGround',
+  'navigation.courseOverGroundTrue',
+  'navigation.headingTrue',
+  'navigation.speedThroughWater',
+  'environment.wind.speedApparent',
+  'environment.wind.angleApparent',
+  'environment.wind.speedTrue',
+  'environment.wind.angleTrueWater',
+  'environment.depth.belowTransducer',
+  'environment.water.temperature',
+  'electrical.batteries.house.voltage',
+  'electrical.batteries.house.capacity.stateOfCharge',
+];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+module.exports = function (app) {
+  const plugin = {};
+  plugin.id = 'telltale-uplink';
+  plugin.name = 'Telltale Uplink';
+  plugin.description = 'Decimated, buffered uplink of SignalK data to the shore collector, with an HMAC-verified command channel, bounded raw-N2K capture, discovery, and gated digital-switching actuation.';
+
+  let queue = null;
+  let sampleTimer = null;
+  let postTimer = null;
+  let seq = Date.now();           // monotonic-ish across restarts
+  let cfgVersion = 0;
+  let capVersion = 0;
+  let live = { sampleIntervalMs: 15000, postIntervalMs: 15000 };
+  const executed = new Set();     // command ids we've run (reported until shore drops them)
+  let posting = false;
+
+  // ---- raw capture / discovery / actuation state ----
+  let sender = null;
+  let tapOff = null;
+  let rawCap = { active: false, pgns: null, maxHz: 5, postIntervalMs: 2000 };
+  let rawBuf = [];
+  let rawTimer = null;
+  let capExpireTimer = null;
+  const statusCache = new Map();  // `127501:<instance>` -> { fields, tsMs } (for read-back)
+  const rateGate = new Map();     // `<pgn>:<src>` -> last accepted ms (maxHz throttle)
+  let disc = null;                // active discovery session { sessionId, corr, ... }
+  let pendingResults = [];        // actuation read-backs to report upstream
+  let pendingCandidates = null;   // discovery candidates to report upstream
+
+  plugin.schema = {
+    type: 'object',
+    required: ['serverUrl', 'ingestToken', 'commandKey'],
+    properties: {
+      serverUrl:   { type: 'string', title: 'Shore collector URL', default: 'https://goblin.dupuis.xyz/api/ingest' },
+      source:      { type: 'string', title: 'Vessel id', default: 'goblin' },
+      ingestToken: { type: 'string', title: 'Ingest token (Bearer, boat → shore)' },
+      commandKey:  { type: 'string', title: 'Command key (shared secret; verifies shore directives)' },
+      sampleIntervalMs: { type: 'number', title: 'Sample interval (ms)', default: 15000 },
+      postIntervalMs:   { type: 'number', title: 'Post interval (ms)', default: 15000 },
+      maxItems:    { type: 'number', title: 'Max buffered samples (disk cap)', default: 40000 },
+      maxBatch:    { type: 'number', title: 'Max samples per POST', default: 500 },
+      paths:       { type: 'array', title: 'Paths to send (empty = sensible default)', items: { type: 'string' } },
+      actuationEnabled: {
+        type: 'boolean', default: false,
+        title: 'Enable actuation (MASTER ARM — leave OFF unless you are actively switching loads)',
+      },
+      actuationTargets: {
+        type: 'array',
+        title: 'Boat-side switching allowlist — the REAL control. Only CONFIRMED, non-excluded entries are remotely actuatable.',
+        items: {
+          type: 'object',
+          properties: {
+            name:     { type: 'string', title: 'Name' },
+            pgn:      { type: 'number', title: 'PGN', default: 127501 },
+            instance: { type: 'number', title: 'Instance' },
+            switch:   { type: 'number', title: 'Switch #' },
+            confirmed:{ type: 'boolean', title: 'Confirmed (Phase-2 closed-loop test passed)', default: false },
+            excluded: { type: 'boolean', title: 'Hard-excluded (never actuate)', default: false },
+          },
+        },
+      },
+    },
+  };
+
+  let opts = {};
+
+  function unwrap(v) {
+    if (v && typeof v === 'object' && v.value !== undefined && v.timestamp !== undefined) return v.value;
+    return v;
+  }
+
+  function snapshot() {
+    const paths = (opts.paths && opts.paths.length) ? opts.paths : DEFAULT_PATHS;
+    const values = {};
+    for (const p of paths) {
+      const v = unwrap(app.getSelfPath(p));
+      if (v !== undefined && v !== null) values[p] = v;
+    }
+    if (Object.keys(values).length === 0) return;
+    queue.append({ seq: ++seq, ts: new Date().toISOString(), values });
+  }
+
+  function postJson(urlStr, headers, bodyObj) {
+    return new Promise((resolve, reject) => {
+      const u = new URL(urlStr);
+      const lib = u.protocol === 'https:' ? https : http;
+      const body = Buffer.from(JSON.stringify(bodyObj));
+      const req = lib.request(
+        { method: 'POST', hostname: u.hostname, port: u.port || (u.protocol === 'https:' ? 443 : 80),
+          path: u.pathname + u.search,
+          headers: { 'content-type': 'application/json', 'content-length': body.length, ...headers },
+          timeout: 20000 },
+        (res) => {
+          let data = '';
+          res.on('data', (c) => (data += c));
+          res.on('end', () => resolve({ status: res.statusCode, body: data }));
+        });
+      req.on('error', reject);
+      req.on('timeout', () => req.destroy(new Error('timeout')));
+      req.write(body); req.end();
+    });
+  }
+
+  function reschedule() {
+    if (sampleTimer) clearInterval(sampleTimer);
+    if (postTimer) clearInterval(postTimer);
+    sampleTimer = setInterval(snapshot, live.sampleIntervalMs);
+    postTimer = setInterval(flush, live.postIntervalMs);
+    app.debug(`timers: sample ${live.sampleIntervalMs}ms, post ${live.postIntervalMs}ms`);
+  }
+
+  // ===================== N2K tap (raw / discovery / read-back) =====================
+
+  // tap only while something needs it (raw capture, discovery, or armed read-back)
+  function tapNeeded() { return rawCap.active || !!disc || !!opts.actuationEnabled; }
+  function ensureTap() {
+    if (tapNeeded() && !tapOff) { tapOff = tapN2K(app, onFrame); app.debug('n2k tap on'); }
+    else if (!tapNeeded() && tapOff) { tapOff(); tapOff = null; app.debug('n2k tap off'); }
+  }
+
+  function onFrame(f) {
+    // keep latest 127501 status per instance for actuation read-back
+    if (f.pgn === 127501) statusCache.set(`127501:${instanceOf(f.fields)}`, { fields: f.fields, tsMs: f.tsMs });
+    // feed an active discovery correlator
+    if (disc) disc.corr.observe(f.pgn, f.fields, f.tsMs);
+    // raw capture window (filtered + rate-limited so cellular stays sane)
+    if (rawCap.active) {
+      const pgns = rawCap.pgns && rawCap.pgns.length ? rawCap.pgns : null;
+      if (!pgns || pgns.includes(f.pgn)) {
+        const rk = `${f.pgn}:${f.src}`;
+        const minGap = 1000 / Math.max(1, rawCap.maxHz);
+        if (f.tsMs - (rateGate.get(rk) || 0) >= minGap) {
+          rateGate.set(rk, f.tsMs);
+          rawBuf.push({ ts: new Date(f.tsMs).toISOString(), pgn: f.pgn, src: f.src, dst: f.dst, fields: f.fields });
+          if (rawBuf.length > 5000) rawBuf.shift(); // bound memory; raw is best-effort
+        }
+      }
+    }
+  }
+
+  const rawUrl = () => opts.serverUrl.replace(/\/api\/ingest\b/, '/api/raw');
+
+  async function postRaw() {
+    if (!rawBuf.length) return;
+    const frames = rawBuf.splice(0, 500);
+    try {
+      await postJson(rawUrl(), { authorization: `Bearer ${opts.ingestToken}` },
+        { source: opts.source || 'goblin', frames });
+    } catch (e) { app.debug(`raw post failed: ${e.message}`); } // drop; raw is best-effort
+  }
+
+  function startCapture(c) {
+    rawCap = {
+      active: true, pgns: c.pgns || null, maxHz: c.maxHz || 5,
+      postIntervalMs: Math.max(1000, c.postIntervalMs || 2000),
+    };
+    ensureTap();
+    if (rawTimer) clearInterval(rawTimer);
+    rawTimer = setInterval(postRaw, rawCap.postIntervalMs);
+    if (capExpireTimer) clearTimeout(capExpireTimer);
+    capExpireTimer = setTimeout(stopCapture, Math.max(1, c.seconds || 60) * 1000);
+    app.setPluginStatus(`raw capture on · ${rawCap.maxHz}Hz · ${c.seconds || 60}s`);
+  }
+  function stopCapture() {
+    if (!rawCap.active) return;
+    rawCap.active = false;
+    if (rawTimer) { clearInterval(rawTimer); rawTimer = null; }
+    if (capExpireTimer) { clearTimeout(capExpireTimer); capExpireTimer = null; }
+    postRaw();
+    ensureTap();
+    app.debug('raw capture off');
+  }
+
+  // ===================== discovery (Phase 1, read-only) =====================
+
+  function startDiscovery(s) {
+    disc = { sessionId: s.sessionId, target: s.target, expected: s.expectedToggles, corr: new Correlator(), timer: null };
+    ensureTap();
+    disc.timer = setTimeout(finishDiscovery, Math.max(1, s.seconds || 30) * 1000);
+    app.setPluginStatus(`discovery: learning "${s.target}" — toggle it now (${s.seconds || 30}s)`);
+    app.debug(`discovery session ${s.sessionId} started for "${s.target}"`);
+  }
+  function finishDiscovery() {
+    if (!disc) return;
+    const candidates = disc.corr.candidates({ expectedToggles: disc.expected }).map((c) => ({
+      pgn: c.pgn, instance: c.instance, switch: c.switch,
+      edges: c.edges, confidence: c.confidence, ambiguousWith: c.ambiguousWith,
+    }));
+    pendingCandidates = { sessionId: disc.sessionId, candidates };
+    app.setPluginStatus(`discovery done: ${candidates.length} candidate(s) for "${disc.target}"`);
+    disc = null;
+    ensureTap();
+    flush(); // report promptly
+  }
+
+  // ===================== actuation (gated; closed-loop) =====================
+
+  function statusFieldsFor(target) {
+    const e = statusCache.get(`127501:${target.instance}`);
+    return e ? e.fields : null;
+  }
+  function currentBit(target) {
+    return actuation.readbackMatches(statusFieldsFor(target), target, true) ? true
+      : actuation.readbackMatches(statusFieldsFor(target), target, false) ? false : null;
+  }
+  async function readback(target, want, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (actuation.readbackMatches(statusFieldsFor(target), target, want)) return true;
+      await sleep(200);
+    }
+    return false;
+  }
+
+  function reportResult(cmd, payload, status, result) {
+    pendingResults.push({ id: cmd.id, logId: payload.logId, status, result: result || null });
+  }
+
+  async function handleActuate(cmd, kind) {
+    const p = cmd.payload || {};
+    const target = p.target || {};
+    const notAfterMs = p.notAfter ? Date.parse(p.notAfter) : null;
+
+    const g = actuation.gate({
+      armed: !!opts.actuationEnabled, allowlist: opts.actuationTargets || [],
+      target, kind, notAfterMs,
+    });
+    if (!g.allow) { app.error(`actuation rejected (${kind}): ${g.reason}`); return reportResult(cmd, p, 'rejected', { reason: g.reason }); }
+    if (!sender || !sender.ready) return reportResult(cmd, p, 'rejected', { reason: 'n2k out not available' });
+
+    // confirm test toggles to the opposite of the current state and verifies the
+    // load followed, then restores it — leaving the boat as found.
+    const orig = currentBit(target);
+    const want = kind === 'confirm' ? (orig == null ? true : !orig) : !!p.state;
+
+    sender.send(actuation.buildSwitchControl(target, want));
+    let ok = await readback(target, want, 2500);
+    let via = '127502';
+    if (!ok) { // fallback to the Command Group Function
+      sender.send(actuation.buildCommandGroupFunction(target, want));
+      ok = await readback(target, want, 2500);
+      via = ok ? '126208' : 'none';
+    }
+
+    if (kind === 'confirm' && ok && orig != null) {
+      sender.send(actuation.buildSwitchControl(target, orig)); // restore
+      await readback(target, orig, 2500);
+    }
+    reportResult(cmd, p, ok ? 'ok' : 'mismatch', { via, state: want, readback: ok });
+  }
+
+  // ===================== directive application =====================
+
+  function applyDirectives(d) {
+    if (d.config && d.config.version > cfgVersion) {
+      cfgVersion = d.config.version;
+      live = {
+        sampleIntervalMs: Math.max(1000, d.config.sampleIntervalMs || live.sampleIntervalMs),
+        postIntervalMs: Math.max(1000, d.config.postIntervalMs || live.postIntervalMs),
+      };
+      app.setPluginStatus(`config v${cfgVersion}: sample ${live.sampleIntervalMs}ms / post ${live.postIntervalMs}ms`);
+      reschedule();
+    }
+
+    if (d.rawCapture && d.rawCapture.version > capVersion) {
+      capVersion = d.rawCapture.version;
+      if (d.rawCapture.active) startCapture(d.rawCapture); else stopCapture();
+    }
+
+    if (d.discovery && (!disc || disc.sessionId !== d.discovery.sessionId)) {
+      // don't re-run a session we already produced candidates for
+      if (!pendingCandidates || pendingCandidates.sessionId !== d.discovery.sessionId) startDiscovery(d.discovery);
+    }
+
+    for (const c of d.commands || []) {
+      if (executed.has(c.id)) continue;
+      executed.add(c.id);
+      if (c.type === 'flushBuffer') flush();
+      else if (c.type === 'actuate') handleActuate(c, 'actuate');
+      else if (c.type === 'confirmTarget') handleActuate(c, 'confirm');
+      else app.debug(`unknown command type ${c.type} (${c.id})`);
+      app.debug(`command ${c.id} ${c.type} handled`);
+    }
+  }
+
+  // ===================== uplink =====================
+
+  function haveSomethingToReport() {
+    return queue.length > 0 || pendingResults.length > 0 || !!pendingCandidates;
+  }
+
+  async function flush() {
+    if (posting || !haveSomethingToReport()) return;
+    posting = true;
+    const sentResults = pendingResults;
+    const sentCandidates = pendingCandidates;
+    try {
+      const batch = queue.peek(opts.maxBatch || 500);
+      const nonce = crypto.randomBytes(16).toString('hex');
+      const body = {
+        source: opts.source || 'goblin', nonce, cfgVersion, capVersion,
+        ackedCommands: [...executed],
+        commandResults: sentResults,
+        discoveryCandidates: sentCandidates || undefined,
+        status: { actuationArmed: !!opts.actuationEnabled, rawCaptureActive: rawCap.active, capVersion },
+        batch,
+      };
+      const { status, body: text } = await postJson(opts.serverUrl, { authorization: `Bearer ${opts.ingestToken}` }, body);
+      if (status !== 200) { app.debug(`post HTTP ${status}`); return; }
+      const resp = JSON.parse(text);
+      queue.dropThrough(resp.ackSeq);
+      // these were accepted by shore — clear them (only the ones we just sent)
+      if (sentResults.length) pendingResults = pendingResults.slice(sentResults.length);
+      if (sentCandidates && pendingCandidates === sentCandidates) pendingCandidates = null;
+
+      if (resp.directives) {
+        if (verify(opts.commandKey, resp.sig, nonce, resp.directives)) applyDirectives(JSON.parse(resp.directives));
+        else app.error('directive signature invalid — ignoring shore commands');
+      }
+      // prune executed ids the shore is no longer sending
+      const stillPending = new Set((resp.directives ? (JSON.parse(resp.directives).commands || []) : []).map((c) => c.id));
+      for (const id of [...executed]) if (!stillPending.has(id)) executed.delete(id);
+
+      const armed = opts.actuationEnabled ? ' · ARMED' : '';
+      const cap = rawCap.active ? ' · CAPTURING' : '';
+      app.setPluginStatus(`buffer ${queue.length} · cfg v${cfgVersion}${cap}${armed}`);
+    } catch (e) {
+      app.debug(`post failed: ${e.message} (buffered ${queue.length})`);
+    } finally {
+      posting = false;
+    }
+  }
+
+  plugin.start = function (options) {
+    opts = options || {};
+    live = {
+      sampleIntervalMs: Math.max(1000, opts.sampleIntervalMs || 15000),
+      postIntervalMs: Math.max(1000, opts.postIntervalMs || 15000),
+    };
+    const file = path.join(app.getDataDirPath(), 'telltale-queue.json');
+    queue = new DiskQueue({ file, maxItems: opts.maxItems || 40000, log: (m) => app.debug(m) });
+    sender = createSender(app, { log: (m) => app.debug(m) });
+    ensureTap(); // on if armed (for read-back); otherwise stays off until a directive
+    reschedule();
+    const armed = opts.actuationEnabled ? ' · ACTUATION ARMED' : '';
+    app.setPluginStatus(`uplink started → ${opts.serverUrl}${armed}`);
+  };
+
+  plugin.stop = function () {
+    if (sampleTimer) clearInterval(sampleTimer);
+    if (postTimer) clearInterval(postTimer);
+    if (rawTimer) clearInterval(rawTimer);
+    if (capExpireTimer) clearTimeout(capExpireTimer);
+    if (disc && disc.timer) clearTimeout(disc.timer);
+    sampleTimer = postTimer = rawTimer = capExpireTimer = null;
+    disc = null;
+    if (tapOff) { tapOff(); tapOff = null; }
+    if (sender) sender.stop();
+    if (queue) queue.stop();
+  };
+
+  return plugin;
+};

package/lib/actuation.js

@@ -0,0 +1,92 @@
+'use strict';
+
+// Digital-switching actuation — the layered safety model from docs/FEATURES.md.
+// The boat-side allowlist is the REAL control: a compromised or buggy shore can
+// only address loads you have locally confirmed. Everything here is pure so the
+// gate logic is unit-tested without a bus.
+
+// Names that must never be remotely actuatable — a wrong/stale/spoofed state could
+// endanger the boat. The UI/boat default-excludes anything matching; this is a
+// belt-and-braces hint, not the only guard (the allowlist is).
+const DANGER_PATTERNS = [
+  /bilge/i, /nav(?:igation)?\s*light/i, /steaming/i, /\bmast\b/i, /anchor light/i,
+  /engine/i, /start(?:er)?/i, /windlass/i, /winch/i, /thruster/i, /\bhelm\b/i,
+  /seacock/i, /valve/i, /fuel/i, /propane|lpg|gas/i,
+];
+function looksDangerous(name) {
+  return DANGER_PATTERNS.some((re) => re.test(String(name || '')));
+}
+
+const sameTarget = (a, b) =>
+  a && b && Number(a.pgn) === Number(b.pgn) &&
+  Number(a.instance) === Number(b.instance) &&
+  Number(a.switch) === Number(b.switch);
+
+function findTarget(allowlist, target) {
+  return (allowlist || []).find((t) => sameTarget(t, target)) || null;
+}
+
+// The single decision point. Returns {allow, reason}.
+//   armed       — master actuation-enable toggle (default OFF on the boat)
+//   allowlist   — locally-configured targets [{pgn,instance,switch,confirmed,excluded}]
+//   target      — {pgn,instance,switch}
+//   kind        — 'actuate' (needs confirmed) | 'confirm' (Phase-2 test; confirmed not required)
+//   nowMs/notAfterMs — TTL: stale commands are dropped, never executed late
+function gate({ armed, allowlist, target, kind = 'actuate', nowMs = Date.now(), notAfterMs = null }) {
+  if (!armed) return { allow: false, reason: 'actuation not armed' };
+  if (!target || target.pgn == null || target.instance == null || target.switch == null) {
+    return { allow: false, reason: 'malformed target' };
+  }
+  if (notAfterMs != null && nowMs > notAfterMs) return { allow: false, reason: 'command expired (TTL)' };
+  const t = findTarget(allowlist, target);
+  if (!t) return { allow: false, reason: 'target not in boat allowlist' };
+  if (t.excluded) return { allow: false, reason: 'target hard-excluded' };
+  if (kind === 'actuate' && !t.confirmed) return { allow: false, reason: 'target not confirmed' };
+  return { allow: true, reason: 'ok' };
+}
+
+// ---- canboat JSON builders for app.emit('nmea2000JsonOut', ...) ----
+// Primary path: 127502 Binary Switch Control. We set just the addressed switch.
+function buildSwitchControl(target, state) {
+  return {
+    pgn: 127502,
+    dst: 255,
+    Instance: Number(target.instance),
+    [`Switch${Number(target.switch)}`]: state ? 'On' : 'Off',
+  };
+}
+
+// Fallback path: 126208 Command Group Function writing the 127501 field directly.
+// Some banks ignore 127502 and only accept the CGF — we try this if the read-back
+// after 127502 shows no change. Field layout is canboat's; validate on the real bus.
+function buildCommandGroupFunction(target, state) {
+  return {
+    pgn: 126208,
+    dst: 255,
+    'Function Code': 'Command',
+    PGN: 127501,
+    'Number of Parameters': 2,
+    list: [
+      { Parameter: 1, Value: Number(target.instance) },                 // Instance field
+      { Parameter: 2 + Number(target.switch), Value: state ? 1 : 0 },   // Indicator<switch>
+    ],
+  };
+}
+
+// Read-back check: did the status frame settle to the state we asked for?
+function readbackMatches(statusFields, target, wantState) {
+  if (!statusFields) return false;
+  const key = Object.keys(statusFields).find((k) => {
+    const m = /^(?:indicator|switch)\s*(\d+)$/i.exec(k);
+    return m && Number(m[1]) === Number(target.switch);
+  });
+  if (!key) return false;
+  const v = String(statusFields[key]).toLowerCase();
+  const bit = v === 'on' || v === '1' || v === 'true';
+  return bit === !!wantState;
+}
+
+module.exports = {
+  gate, findTarget, sameTarget, looksDangerous, DANGER_PATTERNS,
+  buildSwitchControl, buildCommandGroupFunction, readbackMatches,
+};

package/lib/buffer.js

@@ -0,0 +1,78 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+// A small in-memory queue mirrored to one JSON file. Node is single-threaded so
+// array ops are atomic; disk writes are throttled (flash wear) and bounded (the
+// Venus /data partition must never fill — that can reboot the Cerbo).
+class DiskQueue {
+  constructor({ file, maxItems = 40000, maxBytes = 16 * 1024 * 1024, persistMs = 5000, log = () => {} }) {
+    this.file = file;
+    this.maxItems = maxItems;
+    this.maxBytes = maxBytes;
+    this.persistMs = persistMs;
+    this.log = log;
+    this.items = [];
+    this.dirty = false;
+    this._writing = false;
+    this._load();
+    this._timer = setInterval(() => this._maybePersist(), persistMs);
+    if (this._timer.unref) this._timer.unref();
+  }
+
+  _load() {
+    try {
+      const raw = fs.readFileSync(this.file, 'utf8');
+      const arr = JSON.parse(raw);
+      if (Array.isArray(arr)) this.items = arr;
+      this.log(`buffer: loaded ${this.items.length} items`);
+    } catch { /* no file yet */ }
+  }
+
+  append(item) {
+    this.items.push(item);
+    // enforce caps: drop OLDEST first (a stuck link loses the stalest data,
+    // never fills the disk)
+    let dropped = 0;
+    while (this.items.length > this.maxItems) { this.items.shift(); dropped++; }
+    // cheap byte guard: only measure when comfortably large
+    if (this.items.length > 1000 && this._bytes() > this.maxBytes) {
+      while (this.items.length > 500 && this._bytes() > this.maxBytes) { this.items.shift(); dropped++; }
+    }
+    if (dropped) this.log(`buffer: dropped ${dropped} oldest (cap)`);
+    this.dirty = true;
+  }
+
+  peek(n) { return this.items.slice(0, n); }
+  get length() { return this.items.length; }
+
+  // drop everything with seq <= ackSeq (delivery confirmed)
+  dropThrough(ackSeq) {
+    if (ackSeq == null) return;
+    const before = this.items.length;
+    this.items = this.items.filter((it) => it.seq > ackSeq);
+    if (this.items.length !== before) this.dirty = true;
+  }
+
+  _bytes() { return Buffer.byteLength(JSON.stringify(this.items)); }
+
+  _maybePersist() {
+    if (!this.dirty || this._writing) return;
+    this._writing = true;
+    this.dirty = false;
+    const tmp = this.file + '.tmp';
+    const data = JSON.stringify(this.items);
+    fs.writeFile(tmp, data, (err) => {
+      if (err) { this.dirty = true; this._writing = false; return; }
+      fs.rename(tmp, this.file, () => { this._writing = false; });
+    });
+  }
+
+  flushSync() {
+    try { fs.writeFileSync(this.file, JSON.stringify(this.items)); this.dirty = false; } catch { /* */ }
+  }
+
+  stop() { clearInterval(this._timer); this.flushSync(); }
+}
+
+module.exports = { DiskQueue };

package/lib/discovery.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Discovery Phase 1 — passive signature learning.
+//
+// You name a target ("spreader lights") and toggle it a few times with the real
+// physical control. We watch the switching-family PGNs and find the
+// (pgn, instance, switch) whose bit transitions in lockstep with your toggles and
+// is otherwise quiet. Pure + deterministic so it can be unit-tested without a bus.
+
+// PGNs we treat as "switching family" by default. 127501 Binary Status Report is
+// the universal one; CZone/EmpireBus/Victron also emit proprietary status PGNs,
+// which you can add to the capture filter.
+const DEFAULT_SWITCH_PGNS = [127501];
+
+// Truthy mapping for the many ways canboat renders a binary indicator.
+function asBit(v) {
+  if (v === 1 || v === true) return 1;
+  if (v === 0 || v === false || v == null) return 0;
+  const s = String(v).trim().toLowerCase();
+  if (s === 'on' || s === '1' || s === 'true' || s === 'yes') return 1;
+  if (s === 'off' || s === '0' || s === 'false' || s === 'no') return 0;
+  return null; // not a binary field
+}
+
+// Pull every binary switch out of a canboat 127501-style frame. Field names vary
+// across canboat versions: Indicator1..28 / Switch1..28 / "Indicator 1".
+function extractSwitches(fields) {
+  const out = [];
+  if (!fields || typeof fields !== 'object') return out;
+  for (const [k, v] of Object.entries(fields)) {
+    const m = /^(?:indicator|switch)\s*(\d+)$/i.exec(k);
+    if (!m) continue;
+    const bit = asBit(v);
+    if (bit == null) continue;
+    out.push({ switch: Number(m[1]), state: bit });
+  }
+  return out;
+}
+
+function instanceOf(fields) {
+  if (!fields) return 0;
+  const i = fields.Instance ?? fields.instance ?? fields['Switch Bank Instance'];
+  const n = Number(i);
+  return Number.isFinite(n) ? n : 0;
+}
+
+const keyOf = (pgn, instance, sw) => `${pgn}:${instance}:${sw}`;
+
+class Correlator {
+  // markWindowMs: how close a bus edge must be to an operator "mark" to count as aligned
+  constructor({ markWindowMs = 1500 } = {}) {
+    this.markWindowMs = markWindowMs;
+    this.channels = new Map(); // key -> {pgn, instance, switch, last, obs, edges:[ms]}
+    this.marks = [];           // optional operator toggle timestamps (ms)
+  }
+
+  // mark the moment you physically flipped the switch (optional but sharpens it)
+  mark(tsMs) { this.marks.push(tsMs); }
+
+  observe(pgn, fields, tsMs) {
+    const instance = instanceOf(fields);
+    for (const { switch: sw, state } of extractSwitches(fields)) {
+      const key = keyOf(pgn, instance, sw);
+      let ch = this.channels.get(key);
+      if (!ch) { ch = { pgn, instance, switch: sw, last: null, obs: 0, edges: [] }; this.channels.set(key, ch); }
+      ch.obs++;
+      if (ch.last != null && state !== ch.last) ch.edges.push(tsMs);
+      ch.last = state;
+    }
+  }
+
+  // Rank channels into candidate signatures. expectedToggles (if known) is the
+  // number of times you flipped the switch; otherwise we lean on cleanliness.
+  candidates({ expectedToggles = null, maxResults = 5 } = {}) {
+    const chans = [...this.channels.values()].filter((c) => c.edges.length > 0);
+
+    const scored = chans.map((c) => {
+      const edges = c.edges.length;
+      const noise = edges / Math.max(1, c.obs);     // 1.0 == flips every frame (bad)
+      let score;
+
+      if (this.marks.length) {
+        // alignment: fraction of marks that have a bus edge nearby
+        const alignedMarks = this.marks.filter((m) =>
+          c.edges.some((e) => Math.abs(e - m) <= this.markWindowMs)).length;
+        const alignedEdges = c.edges.filter((e) =>
+          this.marks.some((m) => Math.abs(e - m) <= this.markWindowMs)).length;
+        const align = alignedMarks / this.marks.length;          // 0..1 recall
+        const precision = alignedEdges / edges;                  // 0..1 (penalise stray edges)
+        score = align * precision;
+      } else if (expectedToggles != null) {
+        const dist = Math.abs(edges - expectedToggles);
+        score = Math.max(0, 1 - dist / (expectedToggles + 1));
+      } else {
+        // no priors: prefer few, clean edges over constant chatter
+        score = 1 / edges;
+      }
+      score *= (1 - Math.min(0.9, noise)); // always punish chattery channels
+      return { pgn: c.pgn, instance: c.instance, switch: c.switch, edges, obs: c.obs, score, edgeTimes: c.edges };
+    });
+
+    // co-moving channels (same edge pattern within the window) are ambiguous: you
+    // can't tell them apart from the bus alone — surface them so the human picks.
+    for (const a of scored) {
+      a.ambiguousWith = scored
+        .filter((b) => b !== a && sameEdges(a.edgeTimes, b.edgeTimes, this.markWindowMs))
+        .map((b) => ({ pgn: b.pgn, instance: b.instance, switch: b.switch }));
+    }
+
+    return scored
+      .sort((a, b) => b.score - a.score || a.edges - b.edges)
+      .slice(0, maxResults)
+      .map(({ edgeTimes, ...c }) => ({ ...c, confidence: Number(c.score.toFixed(3)) }));
+  }
+}
+
+// two edge-time sets "co-move" if equal length and each pairs within tolerance
+function sameEdges(a, b, tolMs) {
+  if (a.length !== b.length || a.length === 0) return false;
+  for (let i = 0; i < a.length; i++) if (Math.abs(a[i] - b[i]) > tolMs) return false;
+  return true;
+}
+
+module.exports = { Correlator, extractSwitches, instanceOf, asBit, DEFAULT_SWITCH_PGNS };

package/lib/hmac.js

@@ -0,0 +1,20 @@
+'use strict';
+const crypto = require('crypto');
+
+// Wire contract for the shore → boat command channel: HMAC-SHA256 over the
+// concatenation (nonce + directives), both strings, hex-encoded. The collector
+// signs returned directives; the plugin verifies before applying. Keep this the
+// single source of truth — the simulator (shore/tools/simulate-boat.mjs) and the
+// collector reimplement the same formula and must stay in lockstep.
+function sign(key, nonce, directives) {
+  return crypto.createHmac('sha256', key || '').update(String(nonce) + String(directives)).digest('hex');
+}
+
+// Constant-time compare. Returns false (never throws) on missing/malformed hex.
+function verify(key, sig, nonce, directives) {
+  const a = Buffer.from(sig || '', 'hex');
+  const b = Buffer.from(sign(key, nonce, directives), 'hex');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+module.exports = { sign, verify };

package/lib/n2k.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// Thin adaptor over the SignalK server's NMEA 2000 plumbing. Confirmed against
+// signalk-server source (packages/streams/src/canboatjs.ts emits 'N2KAnalyzerOut';
+// docs/develop/plugins send via 'nmea2000JsonOut' once 'nmea2000OutAvailable'):
+//
+//   IN  : app.on('N2KAnalyzerOut', pgn => ...)   // canboat JSON: {pgn,src,dst,fields,...}
+//   OUT : app.emit('nmea2000JsonOut', {pgn,...}) // after 'nmea2000OutAvailable'
+//
+// `app` is just an EventEmitter, so tests pass a fake one.
+
+// Subscribe to the raw canboat-parsed N2K stream. Returns an unsubscribe fn.
+function tapN2K(app, onFrame) {
+  const handler = (pgn) => {
+    if (!pgn || pgn.pgn == null) return;
+    onFrame({
+      pgn: Number(pgn.pgn),
+      src: pgn.src != null ? Number(pgn.src) : null,
+      dst: pgn.dst != null ? Number(pgn.dst) : null,
+      fields: pgn.fields || pgn.data || {},
+      tsMs: pgn.timestamp ? Date.parse(pgn.timestamp) : Date.now(),
+    });
+  };
+  app.on('N2KAnalyzerOut', handler);
+  return () => { try { app.removeListener('N2KAnalyzerOut', handler); } catch { /* */ } };
+}
+
+// A sender that respects provider readiness. The N2K-out provider may not be up at
+// plugin start; we gate on 'nmea2000OutAvailable' and refuse to send until then so
+// commands are never silently dropped into the void.
+function createSender(app, { log = () => {} } = {}) {
+  let ready = false;
+  const onReady = () => { ready = true; log('n2k out available'); };
+  app.on('nmea2000OutAvailable', onReady);
+
+  return {
+    get ready() { return ready; },
+    // Force-ready (e.g. tests, or servers that don't emit the availability event
+    // but do have a writable connection configured).
+    markReady() { ready = true; },
+    send(pgnObject) {
+      if (!ready) return { sent: false, reason: 'n2k out not available' };
+      app.emit('nmea2000JsonOut', pgnObject);
+      return { sent: true };
+    },
+    stop() { try { app.removeListener('nmea2000OutAvailable', onReady); } catch { /* */ } },
+  };
+}
+
+module.exports = { tapN2K, createSender };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "signalk-telltale-plugin",
+  "version": "0.1.0",
+  "description": "Decimated, buffered uplink of SignalK data to the GOBLIN shore collector, with an HMAC-verified command channel, bounded raw-N2K capture, discovery, and gated digital-switching actuation.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-category-utility",
+    "nmea2000",
+    "telltale"
+  ],
+  "signalk-plugin-enabled-by-default": false,
+  "author": "Andrew Dupuis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.dupuis.xyz/andrewdupuis/telltale.git",
+    "directory": "cerbo/telltale-signalk-plugin"
+  },
+  "homepage": "https://gitlab.dupuis.xyz/andrewdupuis/telltale",
+  "bugs": {
+    "url": "https://gitlab.dupuis.xyz/andrewdupuis/telltale/-/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "dependencies": {}
+}