synabun 1.3.0 → 2.0.0-beta

package/neural-interface/lib/whatsapp/paths.js

@@ -0,0 +1,81 @@
+// Where the WhatsApp Link keeps its files.
+//
+//   waHome      credentials (auth/state.db) and the host's cwd. Never inside a
+//               folder a backup copies (BACKUP_DATA_DIRS of backup-service.js:
+//               DATA_HOME/data and DATA_HOME/mcp-data, plus the caller's extra
+//               backup roots): a SYNABUN_WHATSAPP_HOME there is refused with a
+//               warning and the default is used. On Windows it is
+//               %LOCALAPPDATA% so a roaming profile never copies a live
+//               session to a second machine (that ends in connectionReplaced).
+//   runtimeDir  the Baileys runtime, installed on demand from the pinned
+//               lockfile in ./connector (never in a SynaBun package.json).
+//   stagingDir  where the installer builds the next runtime before swapping.
+//   logsDir     SynaBun's shared log folder.
+//
+// Pure: no filesystem access, so callers and tests can resolve any platform.
+
+import path from 'node:path';
+import { BACKUP_DATA_DIRS } from '../backup-service.js';
+
+function pathApi(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+/** True when `candidate` is `parent` or inside it (same platform semantics). */
+export function isInside(candidate, parent, platform = process.platform) {
+  const p = pathApi(platform);
+  const rel = p.relative(p.resolve(parent), p.resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !p.isAbsolute(rel));
+}
+
+/**
+ * @param {{dataHome: string, env?: Record<string,string|undefined>, platform?: string, extraBackupRoots?: string[]}} opts
+ *   `extraBackupRoots`: folders a backup copies besides BACKUP_DATA_DIRS (server.js' additional entries).
+ * @returns {{waHome:string, defaultWaHome:string, authDir:string, runtimeDir:string, stagingDir:string, logsDir:string,
+ *   installLogPath:string, installLockPath:string, npmCacheDir:string, backupRoots:string[], warnings:string[]}}
+ */
+export function resolveWhatsAppPaths({ dataHome, env = process.env, platform = process.platform, extraBackupRoots = [] } = {}) {
+  if (typeof dataHome !== 'string' || !dataHome) throw new TypeError('resolveWhatsAppPaths: dataHome is required');
+  const p = pathApi(platform);
+  const home = p.resolve(dataHome);
+  const dataDir = p.join(home, 'data');
+  const warnings = [];
+  const backupRoots = [...new Set([
+    ...BACKUP_DATA_DIRS.map((dir) => p.join(home, dir)),
+    ...(Array.isArray(extraBackupRoots) ? extraBackupRoots : []).filter((root) => typeof root === 'string' && root).map((root) => p.resolve(root)),
+  ])];
+
+  let defaultWaHome = p.join(home, 'whatsapp');
+  if (platform === 'win32') {
+    const local = env.LOCALAPPDATA || (env.USERPROFILE ? p.join(env.USERPROFILE, 'AppData', 'Local') : '');
+    if (local) defaultWaHome = p.join(p.resolve(local), 'synabun', 'whatsapp');
+  }
+
+  let waHome = defaultWaHome;
+  const override = typeof env.SYNABUN_WHATSAPP_HOME === 'string' ? env.SYNABUN_WHATSAPP_HOME.trim() : '';
+  if (override) {
+    const resolved = p.resolve(override);
+    // Inside a backed-up folder: a backup would copy the live session.
+    const clash = backupRoots.find((root) => isInside(resolved, root, platform));
+    if (clash) {
+      warnings.push(`SYNABUN_WHATSAPP_HOME points inside a backed-up folder (${clash}); using the default location instead`);
+    } else {
+      waHome = resolved;
+    }
+  }
+
+  const runtimeRoot = p.join(home, 'runtime');
+  return {
+    waHome,
+    defaultWaHome,
+    authDir: p.join(waHome, 'auth'),
+    runtimeDir: p.join(runtimeRoot, 'whatsapp'),
+    stagingDir: p.join(runtimeRoot, 'whatsapp.staging'),
+    logsDir: p.join(dataDir, 'logs'),
+    installLogPath: p.join(dataDir, 'whatsapp', 'install.log'),
+    installLockPath: p.join(runtimeRoot, 'whatsapp.install.lock'),
+    npmCacheDir: p.join(home, 'cache', 'npm'),
+    backupRoots,
+    warnings,
+  };
+}

package/neural-interface/lib/whatsapp/protocol.js

@@ -0,0 +1,327 @@
+// WhatsApp Link host protocol — shared by the main-side manager (manager.js)
+// and the child host (host.js → host-core.js). Bump PROTOCOL_VERSION on any
+// incompatible change: the manager kills a host announcing another version.
+//
+// Main ↔ host (child_process IPC, serialization:'advanced'):
+//   main→host  {op, reqId?, ...fields}         every op with a reqId is answered
+//   host→main  {t:'reply', reqId, ok, data? | error:{code, message}}
+//              {t:'ready'|'state'|'qr'|'pairing_code'|'linked'|'owner_bound'|
+//                 'inbound'|'ignored'|'throttled'|'fatal'|'log', ...}
+//
+// Addressing: no op that makes the host talk to WhatsApp carries an address.
+// send/react/presence/read always reach the bound owner (sendToOwner in
+// host-core.js is the only sendMessage call site) and validateOp rejects any
+// address-shaped key on them. Events never carry a JID or a phone number: the
+// schemas below are closed, so a stray field fails validation instead of
+// leaking. The single exception is the claim_start reply, whose wa.me link
+// holds the dedicated account's own number for the local settings tab.
+
+export const PROTOCOL_VERSION = 1;
+
+export const OP = Object.freeze({
+  CONFIGURE: 'configure',
+  CONNECT: 'connect',
+  DISCONNECT: 'disconnect',
+  LOGOUT: 'logout',
+  CONFIRM_OWNER: 'confirm_owner',
+  CLAIM_START: 'claim_start',
+  CLAIM_CANCEL: 'claim_cancel',
+  OWNER_RESET: 'owner_reset',
+  SEND: 'send',
+  REACT: 'react',
+  PRESENCE: 'presence',
+  READ: 'read',
+  STATUS: 'status',
+  SHUTDOWN: 'shutdown',
+  // Test driver for the fake socket; the host refuses it unless the runtime is fake.
+  FAKE: '__fake',
+});
+
+export const EV = Object.freeze({
+  READY: 'ready',
+  REPLY: 'reply',
+  STATE: 'state',
+  QR: 'qr',
+  PAIRING_CODE: 'pairing_code',
+  LINKED: 'linked',
+  OWNER_BOUND: 'owner_bound',
+  INBOUND: 'inbound',
+  IGNORED: 'ignored',
+  THROTTLED: 'throttled',
+  FATAL: 'fatal',
+  LOG: 'log',
+});
+
+/** conn.state values. `held` is set by the manager (crash breaker), never by the host. */
+export const CONN = Object.freeze({
+  IDLE: 'idle',
+  UNLINKED: 'unlinked',
+  CONNECTING: 'connecting',
+  QR: 'qr',
+  PAIRING: 'pairing',
+  AWAITING_CONFIRM: 'awaiting_confirm',
+  OPEN: 'open',
+  RECONNECTING: 'reconnecting',
+  LOGGED_OUT: 'logged_out',
+  REPLACED: 'replaced',
+  FORBIDDEN: 'forbidden',
+  LINK_EXPIRED: 'link_expired',
+  LOCKED: 'locked',
+  HELD: 'held',
+  ERROR: 'error',
+});
+
+export const ERR = Object.freeze({
+  BAD_REQUEST: 'BAD_REQUEST',
+  UNKNOWN_OP: 'UNKNOWN_OP',
+  ADDRESS_FORBIDDEN: 'ADDRESS_FORBIDDEN',
+  RUNTIME_MISSING: 'RUNTIME_MISSING',
+  RUNTIME_ERROR: 'RUNTIME_ERROR',
+  LOCKED: 'LOCKED',
+  // The credential store refused to open: its folder / files could not be made private (0700 / 0600, ours).
+  AUTH_PERMS: 'AUTH_PERMS',
+  NOT_LINKED: 'NOT_LINKED',
+  ALREADY_LINKED: 'ALREADY_LINKED',
+  MODE_MISMATCH: 'MODE_MISMATCH',
+  NOT_CONNECTED: 'NOT_CONNECTED',
+  NOT_CONFIRMED: 'NOT_CONFIRMED',
+  NOT_AWAITING: 'NOT_AWAITING',
+  NO_OWNER: 'NO_OWNER',
+  OWNER_BOUND: 'OWNER_BOUND',
+  PAUSED: 'PAUSED',
+  THROTTLED: 'THROTTLED',
+  TOO_LONG: 'TOO_LONG',
+  BAD_TARGET: 'BAD_TARGET',
+  BAD_PHONE: 'BAD_PHONE',
+  CLAIM_INACTIVE: 'CLAIM_INACTIVE',
+  SEND_FAILED: 'SEND_FAILED',
+  TIMEOUT: 'TIMEOUT',
+  HOST_UNAVAILABLE: 'HOST_UNAVAILABLE',
+  HELD: 'HELD',
+  PROTOCOL_MISMATCH: 'PROTOCOL_MISMATCH',
+  NOT_FAKE: 'NOT_FAKE',
+  INTERNAL: 'INTERNAL',
+});
+
+export const LIMITS = Object.freeze({
+  MAX_TEXT: 3500,
+  MAX_INBOUND_TEXT: 8192,
+  MAX_IMAGE_BYTES: 5242880,
+  MAX_IMAGES: 4,
+  MAX_READ_IDS: 20,
+});
+
+/** Keys that name a WhatsApp recipient. None may appear on send/react/presence/read. */
+export const ADDRESS_KEYS = Object.freeze(['jid', 'to', 'remoteJid', 'chat', 'number', 'participant', 'recipient']);
+
+/** Status reactions the bridge may set on an owner message (null clears it). */
+export const REACTIONS = Object.freeze({
+  seen: '👀',
+  queued: '⏳',
+  done: '✅',
+  failed: '❌',
+  stopped: '⏹️',
+});
+
+export const MODES = Object.freeze(['self', 'dedicated']);
+export const SELF_TRIGGERS = Object.freeze(['all', 'prefix']);
+export const DEFAULT_PREFIX = 'sb';
+
+const ADDRESSLESS_OPS = new Set([OP.SEND, OP.REACT, OP.PRESENCE, OP.READ]);
+const MSG_ID_RE = /^[A-Za-z0-9._:+/=-]{1,128}$/;
+const PREFIX_RE = /^[^\s]{1,16}$/;
+
+// ── Tiny closed-schema checker ──
+// A spec is { field: check } where check(value, present) returns an error
+// string or null. Fields not in the spec are rejected.
+
+const t = {
+  str: (max = 1 << 20) => (v, p) => (!p ? 'is required' : typeof v !== 'string' ? 'must be a string' : v.length > max ? `is longer than ${max}` : null),
+  optStr: (max = 1 << 20) => (v, p) => (!p || v === undefined ? null : typeof v !== 'string' ? 'must be a string' : v.length > max ? `is longer than ${max}` : null),
+  num: () => (v, p) => (!p ? 'is required' : typeof v !== 'number' || !Number.isFinite(v) ? 'must be a finite number' : null),
+  optNum: () => (v, p) => (!p || v === undefined ? null : typeof v !== 'number' || !Number.isFinite(v) ? 'must be a finite number' : null),
+  bool: () => (v, p) => (!p ? 'is required' : typeof v !== 'boolean' ? 'must be a boolean' : null),
+  optBool: () => (v, p) => (!p || v === undefined ? null : typeof v !== 'boolean' ? 'must be a boolean' : null),
+  oneOf: (list) => (v, p) => (!p ? 'is required' : !list.includes(v) ? `must be one of ${list.join('|')}` : null),
+  optOneOf: (list) => (v, p) => (!p || v === undefined ? null : !list.includes(v) ? `must be one of ${list.join('|')}` : null),
+  obj: (spec) => (v, p) => (!p ? 'is required' : checkObject(v, spec)),
+  optObj: (spec) => (v, p) => (!p || v === undefined ? null : checkObject(v, spec)),
+  objOrNull: (spec) => (v, p) => (!p ? 'is required' : v === null ? null : checkObject(v, spec)),
+  plainObj: () => (v, p) => (!p ? 'is required' : !isPlainObject(v) ? 'must be an object' : null),
+  optPlainObj: () => (v, p) => (!p || v === undefined ? null : !isPlainObject(v) ? 'must be an object' : null),
+  counts: () => (v, p) => {
+    if (!p) return 'is required';
+    if (!isPlainObject(v)) return 'must be an object';
+    for (const [k, n] of Object.entries(v)) {
+      if (!/^[a-z_]{1,40}$/.test(k)) return `has a bad key '${k}'`;
+      if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return `.${k} must be a count`;
+    }
+    return null;
+  },
+  msgId: () => (v, p) => (!p ? 'is required' : typeof v !== 'string' || !MSG_ID_RE.test(v) ? 'must be a message id' : null),
+  any: () => () => null,
+};
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && !Buffer.isBuffer(v);
+}
+
+function checkObject(v, spec) {
+  if (!isPlainObject(v)) return 'must be an object';
+  for (const key of Object.keys(v)) {
+    if (!Object.hasOwn(spec, key)) return `has an unknown field '${key}'`;
+  }
+  for (const [key, check] of Object.entries(spec)) {
+    const err = check(v[key], Object.hasOwn(v, key));
+    if (err) return `.${key} ${err}`;
+  }
+  return null;
+}
+
+// ── Prefs (configure) ──
+
+const PREFS_SPEC = {
+  mode: t.optOneOf(MODES),
+  selfTrigger: t.optOneOf(SELF_TRIGGERS),
+  prefix: (v, p) => (!p || v === undefined ? null : typeof v !== 'string' || !PREFIX_RE.test(v) ? 'must be 1-16 non-space characters' : null),
+};
+export const PREF_KEYS = Object.freeze(Object.keys(PREFS_SPEC));
+
+/** Keep only the preference keys the host understands (the service may pass its whole config). */
+export function pickPrefs(prefs) {
+  const out = {};
+  if (!isPlainObject(prefs)) return out;
+  for (const key of PREF_KEYS) if (prefs[key] !== undefined) out[key] = prefs[key];
+  return out;
+}
+
+// ── Ops ──
+
+const LINK_SPEC = {
+  method: t.oneOf(['qr', 'code']),
+  phone: t.optStr(32),
+};
+
+const OP_SPECS = {
+  [OP.CONFIGURE]: { prefs: t.obj(PREFS_SPEC) },
+  [OP.CONNECT]: { purpose: t.oneOf(['run', 'link']), mode: t.optOneOf(MODES), link: t.optObj(LINK_SPEC) },
+  [OP.DISCONNECT]: {},
+  [OP.LOGOUT]: {},
+  [OP.CONFIRM_OWNER]: { accept: t.bool() },
+  [OP.CLAIM_START]: { ttlMs: t.optNum() },
+  [OP.CLAIM_CANCEL]: {},
+  [OP.OWNER_RESET]: {},
+  [OP.SEND]: { text: t.str(LIMITS.MAX_TEXT * 4), replyTo: (v, p) => (!p || v === undefined || v === null ? null : typeof v !== 'string' || !MSG_ID_RE.test(v) ? 'must be a message id' : null) },
+  [OP.REACT]: { id: t.msgId(), reaction: (v, p) => (!p ? 'is required' : v === null || Object.hasOwn(REACTIONS, v) ? null : `must be one of ${Object.keys(REACTIONS).join('|')} or null`) },
+  [OP.PRESENCE]: { state: t.oneOf(['composing', 'paused']) },
+  [OP.READ]: {
+    ids: (v, p) => {
+      if (!p) return 'is required';
+      if (!Array.isArray(v)) return 'must be an array';
+      if (v.length > LIMITS.MAX_READ_IDS) return `holds more than ${LIMITS.MAX_READ_IDS} ids`;
+      return v.every((id) => typeof id === 'string' && MSG_ID_RE.test(id)) ? null : 'must hold message ids';
+    },
+  },
+  [OP.STATUS]: {},
+  [OP.SHUTDOWN]: {},
+  [OP.FAKE]: { action: t.str(64), args: t.optPlainObj() },
+};
+
+/** @returns {{ok:true} | {ok:false, code:string, message:string}} */
+export function validateOp(msg) {
+  if (!isPlainObject(msg)) return { ok: false, code: ERR.BAD_REQUEST, message: 'op must be an object' };
+  const spec = OP_SPECS[msg.op];
+  if (!spec) return { ok: false, code: ERR.UNKNOWN_OP, message: `unknown op '${String(msg.op).slice(0, 40)}'` };
+  if (ADDRESSLESS_OPS.has(msg.op)) {
+    const found = ADDRESS_KEYS.find((k) => Object.hasOwn(msg, k));
+    if (found) return { ok: false, code: ERR.ADDRESS_FORBIDDEN, message: `${msg.op} never takes an address ('${found}')` };
+  }
+  if (msg.reqId !== undefined && !(Number.isSafeInteger(msg.reqId) && msg.reqId > 0)) {
+    return { ok: false, code: ERR.BAD_REQUEST, message: 'reqId must be a positive integer' };
+  }
+  const { op: _op, reqId: _reqId, ...fields } = msg;
+  const err = checkObject(fields, spec);
+  return err ? { ok: false, code: ERR.BAD_REQUEST, message: `${msg.op}${err.startsWith('.') ? '' : ' '}${err}` } : { ok: true };
+}
+
+// ── Events ──
+
+const MASKED_ME = t.objOrNull({ masked: t.str(64), name: (v, p) => (!p ? 'is required' : v === null || (typeof v === 'string' && v.length <= 100) ? null : 'must be a short string or null') });
+const OWNER_INFO = t.objOrNull({ bound: t.bool(), masked: (v, p) => (!p ? 'is required' : v === null || (typeof v === 'string' && v.length <= 64) ? null : 'must be a short string or null') });
+
+export const CONN_SPEC = {
+  state: t.oneOf(Object.values(CONN)),
+  mode: (v, p) => (!p ? 'is required' : v === null || MODES.includes(v) ? null : 'must be a mode or null'),
+  registered: t.bool(),
+  me: MASKED_ME,
+  owner: OWNER_INFO,
+  lastDisconnect: t.objOrNull({ reason: t.str(64), code: (v, p) => (!p ? 'is required' : v === null || Number.isFinite(v) ? null : 'must be a number or null'), at: t.num() }),
+  retryInMs: (v, p) => (!p ? 'is required' : v === null || (Number.isFinite(v) && v >= 0) ? null : 'must be a delay or null'),
+  counters: t.counts(),
+  paused: t.bool(),
+  awaitingConfirmUntil: (v, p) => (!p ? 'is required' : v === null || Number.isFinite(v) ? null : 'must be a time or null'),
+  claim: t.objOrNull({ active: t.bool(), expiresAt: t.num(), attemptsLeft: t.num() }),
+  lastError: (v, p) => (!p ? 'is required' : v === null || (typeof v === 'string' && v.length <= 200) ? null : 'must be a short string or null'),
+};
+
+export const RUNTIME_SPEC = {
+  loaded: t.bool(),
+  version: (v, p) => (!p ? 'is required' : v === null || (typeof v === 'string' && v.length <= 40) ? null : 'must be a version or null'),
+  fake: t.bool(),
+  error: (v, p) => (!p ? 'is required' : v === null || (typeof v === 'string' && v.length <= 200) ? null : 'must be a short string or null'),
+};
+
+const IMAGE_SPEC = { base64: t.str(Math.ceil(LIMITS.MAX_IMAGE_BYTES / 3) * 4 + 4), mediaType: t.oneOf(['image/jpeg', 'image/png', 'image/webp']), bytes: t.num() };
+
+export const INBOUND_SPEC = {
+  id: t.msgId(),
+  ts: t.num(),
+  chat: t.oneOf(['self', 'dm']),
+  text: t.str(LIMITS.MAX_INBOUND_TEXT),
+  images: (v, p) => {
+    if (!p) return 'is required';
+    if (!Array.isArray(v)) return 'must be an array';
+    if (v.length > LIMITS.MAX_IMAGES) return `holds more than ${LIMITS.MAX_IMAGES} images`;
+    for (const img of v) {
+      const err = checkObject(img, IMAGE_SPEC);
+      if (err) return `[]${err}`;
+    }
+    return null;
+  },
+  unsupported: t.objOrNull({ type: t.str(40), reason: t.optStr(40) }),
+  forwarded: t.bool(),
+  quoted: t.objOrNull({ id: t.msgId(), text: t.str(LIMITS.MAX_INBOUND_TEXT), fromBot: t.bool() }),
+  owner: (v, p) => (!p ? 'is required' : v === true ? null : 'must be true'),
+  // Delivered after an offline spell (messages.upsert 'append'); `ts` says when it was sent.
+  backlog: t.optBool(),
+};
+
+const EVENT_SPECS = {
+  [EV.READY]: { protocol: t.num(), pid: t.num(), runtime: t.obj(RUNTIME_SPEC), conn: t.obj(CONN_SPEC) },
+  [EV.REPLY]: {
+    reqId: t.num(),
+    ok: t.bool(),
+    data: t.any(),
+    error: t.optObj({ code: t.str(40), message: t.optStr(500), retryAfterMs: t.optNum() }),
+  },
+  [EV.STATE]: { conn: t.obj(CONN_SPEC) },
+  [EV.QR]: { qr: t.str(4096), expiresAt: t.num() },
+  [EV.PAIRING_CODE]: { code: t.str(16), expiresAt: t.num() },
+  [EV.LINKED]: { mode: t.oneOf(MODES), me: MASKED_ME },
+  [EV.OWNER_BOUND]: { masked: t.str(64), via: t.oneOf(['claim', 'self_confirm']) },
+  [EV.INBOUND]: { message: t.obj(INBOUND_SPEC) },
+  [EV.IGNORED]: { counts: t.counts() },
+  [EV.THROTTLED]: { retryAfterMs: t.num() },
+  [EV.FATAL]: { code: t.str(40), message: t.optStr(500) },
+  [EV.LOG]: { level: t.oneOf(['debug', 'info', 'warn', 'error']), message: t.str(4000) },
+};
+
+/** @returns {{ok:true} | {ok:false, code:string, message:string}} */
+export function validateEvent(msg) {
+  if (!isPlainObject(msg)) return { ok: false, code: ERR.BAD_REQUEST, message: 'event must be an object' };
+  const spec = EVENT_SPECS[msg.t];
+  if (!spec) return { ok: false, code: ERR.UNKNOWN_OP, message: `unknown event '${String(msg.t).slice(0, 40)}'` };
+  const { t: _t, ...fields } = msg;
+  const err = checkObject(fields, spec);
+  return err ? { ok: false, code: ERR.BAD_REQUEST, message: `${msg.t}${err.startsWith('.') ? '' : ' '}${err}` } : { ok: true };
+}

package/neural-interface/lib/whatsapp/qr-svg.js

@@ -0,0 +1,57 @@
+// QR codes for the WhatsApp settings tab: the link QR (Baileys' pairing ref)
+// and the claim card's wa.me QR, drawn server-side with Project Nayuki's
+// generator (vendor/qrcodegen.js, MIT) so no QR library ever ships to the page.
+//
+// Output is one self-contained SVG: a white background and ONE <path> with
+// every dark module, black, shape-rendering="crispEdges" so it stays sharp
+// at any size (the tab shows it at >= 240 px through an <img> data URI). The
+// encoded text never reaches an attribute or the markup: only the module grid
+// does, and the accessible name is a fixed label.
+
+import { qrcodegen } from './vendor/qrcodegen.js';
+
+const ECC = Object.freeze({
+  L: qrcodegen.QrCode.Ecc.LOW,
+  M: qrcodegen.QrCode.Ecc.MEDIUM,
+  Q: qrcodegen.QrCode.Ecc.QUARTILE,
+  H: qrcodegen.QrCode.Ecc.HIGH,
+});
+
+const escapeAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/'/g, '&#39;');
+
+/** The module grid for `text`: { size, dark(x, y) }. Throws RangeError when the text is too long for a QR code. */
+export function encodeQr(text, { ecc = 'M' } = {}) {
+  if (typeof text !== 'string' || !text) throw new TypeError('encodeQr: text must be a non-empty string');
+  const level = ECC[String(ecc).toUpperCase()];
+  if (!level) throw new RangeError(`encodeQr: ecc must be one of ${Object.keys(ECC).join(', ')}`);
+  const qr = qrcodegen.QrCode.encodeText(text, level);
+  return { size: qr.size, version: qr.version, dark: (x, y) => qr.getModule(x, y) };
+}
+
+/**
+ * @param {string} text   what the code encodes (never echoed into the SVG)
+ * @param {{ecc?: 'L'|'M'|'Q'|'H', border?: number, label?: string}} [opts]
+ *   border: quiet zone in modules (0-16, default 4 — the spec's minimum)
+ * @returns {string} `<svg …>` markup
+ */
+export function renderQrSvg(text, { ecc = 'M', border = 4, label = 'QR code' } = {}) {
+  const b = Number.isInteger(border) && border >= 0 && border <= 16 ? border : 4;
+  const { size, dark } = encodeQr(text, { ecc });
+  const dim = size + b * 2;
+  // One subpath per horizontal run of dark modules keeps the path short.
+  let d = '';
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (!dark(x, y)) continue;
+      let run = 1;
+      while (x + run < size && dark(x + run, y)) run++;
+      d += `M${x + b},${y + b}h${run}v1h-${run}z`;
+      x += run - 1;
+    }
+  }
+  const name = escapeAttr(String(label || 'QR code').slice(0, 80));
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${dim} ${dim}" role="img" aria-label="${name}" shape-rendering="crispEdges">`
+    + `<rect width="${dim}" height="${dim}" fill="#FFFFFF"/>`
+    + `<path d="${d}" fill="#000000"/>`
+    + '</svg>';
+}

package/neural-interface/lib/whatsapp/redact.js

@@ -0,0 +1,130 @@
+// Log redaction for the WhatsApp Link. Everything the host or its runtime
+// prints passes through redactWa before it reaches a SynaBun log: phone
+// numbers, JIDs, QR payloads, pairing/claim codes, the Autonomous "ALLOW 1234"
+// answer, key material and the credential shapes the Jev secret gate knows about.
+//
+// JIDs become `self`, `owner` or `other#<hmac8>`. The HMAC key is random per
+// process, so the same stranger keeps one tag inside a log without the tag
+// being reversible or comparable across processes. The host tells this module
+// who self and owner are (setRedactionContext); the main process never learns
+// a JID, so there everything is `other#…`.
+
+import { createHmac, randomBytes } from 'node:crypto';
+
+/**
+ * Mirror of CREDENTIAL_PATTERNS in mcp-server/src/services/typesafe-config.ts
+ * (tests/whatsapp-redact.test.mjs fails when the two lists drift apart).
+ */
+export const CREDENTIAL_PATTERNS = [
+  { type: 'private-key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, precise: true },
+  { type: 'api-key', re: /\b(?:sk|rk|pk)[-_](?:live|test|proj|ant|or|api)?[-_]?[A-Za-z0-9_-]{16,}/g, precise: true },
+  { type: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, precise: true },
+  { type: 'slack-token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, precise: true },
+  { type: 'aws-key', re: /\bAKIA[0-9A-Z]{16}\b/g, precise: true },
+  { type: 'jwt', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, precise: true },
+  { type: 'bearer', re: /\bBearer\s+([A-Za-z0-9._~+/=-]{16,})/g, group: 1, precise: false },
+  { type: 'secret', re: /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|secret[_-]?key|client[_-]?secret|password|passwd|pwd|token|secret|authorization)\s*["']?\s*[:=]\s*["']?([^\s"',;]{8,})/gi, group: 1, precise: false },
+];
+
+const HMAC_KEY = randomBytes(32);
+let context = { self: new Set(), owner: new Set() };
+
+const SERVERS = 's\\.whatsapp\\.net|c\\.us|hosted\\.lid|hosted|lid|g\\.us|broadcast|newsletter';
+const JID_RE = new RegExp(`(?<![A-Za-z0-9._%+-])([A-Za-z0-9-]{1,64})(?:_\\d{1,3})?(?::\\d{1,4})?@(${SERVERS})(?![A-Za-z0-9.-])`, 'g');
+const QR_URL_RE = /https?:\/\/wa\.me\/settings\/linked_devices#[^\s"'<>)\]]+/g;
+const QR_REF_RE = /(?<![A-Za-z0-9])\d@[A-Za-z0-9+/=_-]{16,}(?:,[A-Za-z0-9+/=_-]{8,})*/g;
+const BUFFER_DUMP_RE = /<Buffer(?: [0-9a-f]{2})*(?: \.\.\. \d+ more bytes?)?>/g;
+const TYPED_ARRAY_DUMP_RE = /\b(?:Uint8Array|Buffer|ArrayBuffer)\(\d+\) \[[^\]]*\]/g;
+const BYTE_ARRAY_RE = /\[(?:\s*\d{1,3}\s*,){7,}\s*\d{1,3}\s*\]/g;
+const CLAIM_CODE_RE = /\bSB-\d{6}\b/gi;
+const ALLOW_CODE_RE = /\b(allow)\s+\d{4}\b/gi;
+const PAIRING_DASH_RE = /\b[1-9A-HJ-NP-TV-Z]{4}-[1-9A-HJ-NP-TV-Z]{4}\b/g;
+const PAIRING_BARE_RE = /\b(?=[1-9A-HJ-NP-TV-Z]{8}\b)(?=[A-Z]*[1-9])(?=[1-9]*[A-Z])[1-9A-HJ-NP-TV-Z]{8}\b/g;
+const HEX_RE = /\b[0-9a-fA-F]{24,}\b/g;
+const B64_RE = /(?<![A-Za-z0-9+/=_-])[A-Za-z0-9+/_-]{24,}={0,2}(?![A-Za-z0-9+/=_-])/g;
+const NUMBER_RE = /(?<![A-Za-z0-9_#])\+?\(?\d(?:[ .()-]{0,2}\d){6,}(?![A-Za-z0-9_])/g;
+const DATE_LIKE_RE = /^\d{4}-\d{2}-\d{2}$|^\d{2}:\d{2}:\d{2}/;
+
+function userKey(user, server) {
+  const s = server === 'c.us' ? 's.whatsapp.net' : server === 'hosted' ? 's.whatsapp.net' : server === 'hosted.lid' ? 'lid' : server;
+  return `${s}:${user}`;
+}
+
+function toKeys(list) {
+  const out = new Set();
+  for (const jid of list || []) {
+    if (typeof jid !== 'string') continue;
+    const m = /^([A-Za-z0-9-]{1,64})(?:_\d{1,3})?(?::\d{1,4})?@(.+)$/.exec(jid.trim());
+    if (m) out.add(userKey(m[1], m[2]));
+  }
+  return out;
+}
+
+/** The host's own account and the bound owner (JIDs in any form); called whenever either changes. */
+export function setRedactionContext({ self = [], owner = [] } = {}) {
+  context = { self: toKeys(self), owner: toKeys(owner) };
+}
+
+export function tagFor(user, server) {
+  const key = userKey(user, server);
+  if (context.self.has(key)) return 'self';
+  if (context.owner.has(key)) return 'owner';
+  return `other#${createHmac('sha256', HMAC_KEY).update(key).digest('hex').slice(0, 8)}`;
+}
+
+function redactCredentials(text) {
+  const spans = [];
+  for (const pattern of CREDENTIAL_PATTERNS) {
+    pattern.re.lastIndex = 0;
+    for (const match of text.matchAll(pattern.re)) {
+      const whole = match[0];
+      const secret = pattern.group ? match[pattern.group] : whole;
+      if (!secret) continue;
+      const start = (match.index ?? 0) + (pattern.group ? whole.indexOf(secret) : 0);
+      spans.push({ start, end: start + secret.length, type: pattern.type });
+    }
+  }
+  if (!spans.length) return text;
+  spans.sort((a, b) => a.start - b.start || b.end - a.end);
+  let out = '';
+  let cursor = 0;
+  for (const span of spans) {
+    if (span.start < cursor) continue;
+    out += text.slice(cursor, span.start) + `[redacted:${span.type}]`;
+    cursor = span.end;
+  }
+  return out + text.slice(cursor);
+}
+
+function looksLikeKey(run) {
+  if (/[+=]/.test(run)) return /\d/.test(run) || run.length >= 32;
+  return /\d/.test(run) && /[A-Z]/.test(run) && /[a-z]/.test(run);
+}
+
+/** Redact one log line / message. Accepts anything; always returns a string. */
+export function redactWa(value) {
+  let text;
+  if (typeof value === 'string') text = value;
+  else if (value instanceof Error) text = `${value.name}: ${value.message}`;
+  else {
+    try { text = String(value); } catch { text = '[unprintable]'; }
+  }
+  if (!text) return '';
+  text = redactCredentials(text);
+  text = text.replace(QR_URL_RE, '[qr]').replace(QR_REF_RE, '[qr]');
+  text = text.replace(BUFFER_DUMP_RE, '[buffer]').replace(TYPED_ARRAY_DUMP_RE, '[bytes]').replace(BYTE_ARRAY_RE, '[bytes]');
+  text = text.replace(JID_RE, (_m, user, server) => tagFor(user, server));
+  text = text.replace(ALLOW_CODE_RE, (_m, word) => `${word} [code]`);
+  text = text.replace(CLAIM_CODE_RE, '[code]').replace(PAIRING_DASH_RE, '[code]').replace(PAIRING_BARE_RE, '[code]');
+  text = text.replace(HEX_RE, '[key]').replace(B64_RE, (run) => (looksLikeKey(run) ? '[key]' : run));
+  text = text.replace(NUMBER_RE, (run) => (DATE_LIKE_RE.test(run) ? run : '[number]'));
+  return text;
+}
+
+/** A phone number for display: never more than the last four digits. */
+export function maskNumber(digits) {
+  const d = String(digits ?? '').replace(/\D/g, '');
+  if (d.length >= 8) return `••••${d.slice(-4)}`;
+  if (d.length >= 5) return `••${d.slice(-2)}`;
+  return '••••';
+}