synabun 1.3.0 → 2.0.0

package/neural-interface/lib/desktop/frames.js

@@ -0,0 +1,77 @@
+// ═══════════════════════════════════════════
+// SynaBun — Desktop frames (screenshots as evidence)
+// ═══════════════════════════════════════════
+//
+// Every screenshot becomes a frame: a short-lived screenshot_id, the capture
+// bounds (for coordinate mapping), the JPEG bytes (served to the UI by URL),
+// and a sha256 (audit). Coordinate actions resolve against their owner's
+// LATEST frame, which must be fresh: taken after the owner's last mutating
+// action, within the TTL, and with no user input or display change since.
+// Frames live in memory only (a bounded ring); nothing is written to disk.
+
+import { createHash, randomBytes } from 'node:crypto';
+
+export function createFrameStore({ now = Date.now, ttlMs = () => 120_000, memoryCount = () => 60, random = (n) => randomBytes(n).toString('hex') } = {}) {
+  const frames = new Map();   // frameId → frame (insertion order = age)
+  const latest = new Map();   // ownerKey → frameId (evidence frames only)
+  const ttl = () => (typeof ttlMs === 'function' ? ttlMs() : ttlMs);
+  const cap = () => Math.max(4, Number(typeof memoryCount === 'function' ? memoryCount() : memoryCount) || 60);
+
+  function prune() {
+    while (frames.size > cap()) {
+      const oldest = frames.keys().next().value;
+      frames.delete(oldest);
+      for (const [owner, id] of latest) if (id === oldest) latest.delete(owner);
+    }
+  }
+
+  /**
+   * shot: helper screenshot result { displayId, bounds, image:{w,h,mime,data(base64)}, cursor, frontmost, capturedAt }
+   * evidence:false for zoom captures (never used for coordinate mapping).
+   */
+  function add(ownerKeyValue, shot, { evidence = true, kind = 'screenshot' } = {}) {
+    const bytes = Buffer.from(String(shot?.image?.data || ''), 'base64');
+    const frame = {
+      id: `f_${random(5)}`,
+      screenshotId: `s_${random(6)}`,
+      owner: ownerKeyValue,
+      kind,
+      displayId: shot?.displayId ?? null,
+      bounds: shot?.bounds || null,
+      image: { w: Number(shot?.image?.w) || 0, h: Number(shot?.image?.h) || 0, mime: shot?.image?.mime || 'image/jpeg' },
+      bytes,
+      sha256: createHash('sha256').update(bytes).digest('hex'),
+      cursor: shot?.cursor || null,
+      frontmost: shot?.frontmost || null,
+      capturedAt: now(),
+      stale: false,
+      staleReason: null,
+    };
+    frames.set(frame.id, frame);
+    if (evidence && ownerKeyValue) latest.set(ownerKeyValue, frame.id);
+    prune();
+    return frame;
+  }
+  function get(id) { return frames.get(String(id)) || null; }
+  function latestFor(ownerKeyValue) { const id = latest.get(ownerKeyValue); return id ? frames.get(id) || null : null; }
+  /** Mark evidence stale: one owner's (after its own mutating action) or everyone's ('*'). */
+  function markStale(ownerKeyValue, reason) {
+    for (const [owner, id] of latest) {
+      if (ownerKeyValue !== '*' && owner !== ownerKeyValue) continue;
+      const frame = frames.get(id);
+      if (frame && !frame.stale) { frame.stale = true; frame.staleReason = reason; }
+    }
+  }
+  /** → { ok:true, frame } | { ok:false, reason } */
+  function fresh(ownerKeyValue, screenshotId = null) {
+    const frame = latestFor(ownerKeyValue);
+    if (!frame) return { ok: false, reason: 'no screenshot yet — take one first' };
+    if (screenshotId && frame.screenshotId !== screenshotId) return { ok: false, reason: `screenshot ${screenshotId} is not your latest (${frame.screenshotId})` };
+    if (frame.stale) return { ok: false, reason: `the screen may have changed (${frame.staleReason})` };
+    if (now() - frame.capturedAt > ttl()) return { ok: false, reason: 'the latest screenshot is too old' };
+    return { ok: true, frame };
+  }
+  function drop(ownerKeyValue) { latest.delete(ownerKeyValue); }
+  function clear() { frames.clear(); latest.clear(); }
+  return { add, get, latestFor, markStale, fresh, drop, clear, size: () => frames.size };
+}

package/neural-interface/lib/desktop/grants.js

@@ -0,0 +1,84 @@
+// ═══════════════════════════════════════════
+// SynaBun — Desktop grants (who may drive the computer)
+// ═══════════════════════════════════════════
+//
+// MCP terminal pins cannot say which assistant session a call belongs to (a
+// Codex brain pins codex-sp-<uuid>, an OpenCode brain assistant-oc-<24>), and
+// hosts auto-allow every SynaBun tool. So the Neural Interface mints an
+// unforgeable token per assistant brain and per computer-use worker run; the
+// MCP `computer` group is advertised only to callers presenting one, and every
+// /api/desktop agent route re-resolves it. Tokens live in memory only.
+//
+// A grant can be held: its token exists (a brain's MCP headers are fixed when
+// the brain starts) but resolves to nothing until it is activated. A remote
+// (WhatsApp) session's brain grant is minted held and is active only while
+// lib/remote-policy.js remoteComputerUse allows the running turn.
+
+import { randomBytes } from 'node:crypto';
+
+export const GRANT_RE = /^sbd_[A-Za-z0-9_-]{43}$/;
+
+export function isGrantToken(value) { return typeof value === 'string' && GRANT_RE.test(value); }
+
+export function createGrantRegistry({ now = Date.now, random = () => randomBytes(32) } = {}) {
+  const byToken = new Map();
+
+  /**
+   * meta: { kind:'brain'|'run', assistantSessionId, runId, provider, model, vision,
+   *         held (minted inactive), remote: { channel, approval } (a remote session's grant) }
+   */
+  function mint(meta = {}) {
+    const token = `sbd_${random().toString('base64url').slice(0, 43)}`;
+    byToken.set(token, {
+      token, kind: meta.kind === 'run' ? 'run' : 'brain',
+      assistantSessionId: meta.assistantSessionId ? String(meta.assistantSessionId) : null,
+      runId: meta.runId ? String(meta.runId) : null,
+      provider: meta.provider || null, model: meta.model || null, vision: meta.vision ?? null,
+      held: meta.held === true, remote: cleanRemote(meta.remote),
+      createdAt: now(),
+    });
+    return token;
+  }
+  /** A held grant resolves to nothing: its holder is refused like a caller without one. */
+  function resolve(token) {
+    const grant = isGrantToken(token) ? byToken.get(token) || null : null;
+    return grant && !grant.held ? grant : null;
+  }
+  /**
+   * Activate or hold a grant (unknown token: false). `remote` says where the
+   * session is driven from and how this use was allowed; it rides on the audit.
+   */
+  function setActive(token, active, { remote } = {}) {
+    const grant = isGrantToken(token) ? byToken.get(token) : null;
+    if (!grant) return false;
+    grant.held = active !== true;
+    if (remote !== undefined) grant.remote = cleanRemote(remote);
+    return true;
+  }
+  function isHeld(token) { const grant = isGrantToken(token) ? byToken.get(token) : null; return !!grant && grant.held === true; }
+  function revoke(token) { return byToken.delete(token); }
+  /** Revoke by token, run id or session id (a session's own brain grants only). */
+  function revokeFor({ token = null, runId = null, assistantSessionId = null } = {}) {
+    let removed = 0;
+    for (const [key, grant] of byToken) {
+      if ((token && key === token) || (runId && grant.runId === String(runId)) || (assistantSessionId && grant.kind === 'brain' && grant.assistantSessionId === String(assistantSessionId))) {
+        byToken.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  function list() { return [...byToken.values()].map(({ token, ...rest }) => ({ ...rest, token: `${token.slice(0, 8)}…` })); }
+  function clear() { byToken.clear(); }
+  return { mint, resolve, setActive, isHeld, revoke, revokeFor, list, clear };
+}
+
+/** { channel, approval: 'unasked' | 'approved_turn', approvedBy } of a remote session's grant, else null. */
+function cleanRemote(value) {
+  if (!value || typeof value !== 'object') return null;
+  const channel = String(value.channel || '').trim().slice(0, 40);
+  if (!channel) return null;
+  const approval = value.approval === 'unasked' || value.approval === 'approved_turn' ? value.approval : null;
+  const approvedBy = approval === 'approved_turn' && (value.approvedBy === 'whatsapp' || value.approvedBy === 'ui') ? value.approvedBy : null;
+  return { channel, approval, ...(approvedBy ? { approvedBy } : {}) };
+}

package/neural-interface/lib/desktop/guards.js

@@ -0,0 +1,170 @@
+// ═══════════════════════════════════════════
+// SynaBun — Desktop guards (pure)
+// ═══════════════════════════════════════════
+//
+// Computer use is fully autonomous (no approval cards). What stays: the app
+// blocklist, web browsers (guards.browserApps / browserAppPrefixes: web pages go
+// through the SynaBun browser tools), protected windows and the password-field
+// guard (enforced by the helper at act time, from the GuardSpec built here),
+// plus NON-blocking warnings attached to tool results and the audit log:
+// payment / publish / destructive targets (the browser risk lexicon),
+// card-number-like typing and on-screen text that addresses the agent (prompt
+// injection is data, never instructions).
+
+const MODIFIERS = new Map([
+  ['cmd', 'cmd'], ['command', 'cmd'], ['super', 'cmd'], ['meta', 'cmd'], ['win', 'cmd'],
+  ['shift', 'shift'],
+  ['alt', 'alt'], ['option', 'alt'], ['opt', 'alt'],
+  ['ctrl', 'ctrl'], ['control', 'ctrl'],
+  ['fn', 'fn'],
+]);
+
+/** "cmd+shift+t" / "ctrl+a" / "Return" → { modifiers:[...], key, printable } */
+export function parseCombo(combo) {
+  const parts = String(combo || '').split('+').map((part) => part.trim()).filter(Boolean);
+  const modifiers = [];
+  let key = null;
+  for (const part of parts) {
+    const mod = MODIFIERS.get(part.toLowerCase());
+    if (mod) { if (!modifiers.includes(mod)) modifiers.push(mod); }
+    else key = part;
+  }
+  const hasCommand = modifiers.includes('cmd') || modifiers.includes('ctrl');
+  const single = !!key && [...key].length === 1;
+  const paste = modifiers.includes('cmd') && /^v$/i.test(key || '');
+  return { modifiers, key, printable: (single && !hasCommand) || paste, paste };
+}
+
+/** Modifier list for clicks (Anthropic passes held keys in `text`, e.g. "shift" or "cmd+shift"). */
+export function clickModifiers(text) {
+  if (!text) return [];
+  return parseCombo(text).modifiers;
+}
+
+function luhn(digits) {
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (double) { d *= 2; if (d > 9) d -= 9; }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+/** true when the text contains a 13-19 digit, Luhn-valid number (spaces/dashes allowed). */
+export function looksLikeCardNumber(text) {
+  const candidates = String(text || '').match(/\b(?:\d[ -]?){13,19}\b/g) || [];
+  return candidates.some((candidate) => { const digits = candidate.replace(/\D/g, ''); return digits.length >= 13 && digits.length <= 19 && luhn(digits); });
+}
+
+/** Case-insensitive bundle-id prefix test (same as protocol.js hasBundlePrefix). */
+function hasPrefix(bundleId, prefixes) {
+  if (!bundleId || !Array.isArray(prefixes)) return false;
+  const id = String(bundleId).toLowerCase();
+  return prefixes.some((prefix) => typeof prefix === 'string' && prefix && id.startsWith(prefix.toLowerCase()));
+}
+
+export const BROWSER_RULE_ID = 'web-browsers';
+export const BROWSER_RULE_REASON = 'a web browser: use the SynaBun browser tools (browser_navigate, browser_snapshot, browser_screenshot …) for web pages';
+
+/**
+ * The web browsers as one blocked-app rule, from guards.browserApps (bundle
+ * ids) and guards.browserAppPrefixes (installed web apps): every click, key,
+ * type, drag, scroll, AX action, open and focus whose target is one is refused
+ * by the helper (BLOCKED_APP). By bundle id only: MoreLogin's profile windows
+ * and its manager app share the name "MoreLogin". Null when both lists are empty.
+ */
+export function browserGuardRule(config = {}) {
+  const guards = config.guards || {};
+  const bundleIds = (Array.isArray(guards.browserApps) ? guards.browserApps : []).filter((id) => typeof id === 'string' && id);
+  const bundlePrefixes = (Array.isArray(guards.browserAppPrefixes) ? guards.browserAppPrefixes : []).filter((prefix) => typeof prefix === 'string' && prefix);
+  if (!bundleIds.length && !bundlePrefixes.length) return null;
+  return { id: BROWSER_RULE_ID, bundleIds, bundlePrefixes, reason: BROWSER_RULE_REASON };
+}
+
+/**
+ * GuardSpec for the helper's `configure` command. Protocol 2 fields pass
+ * through: bundlePrefixes (both rule kinds) and appNameRe (protected windows).
+ * A protected rule with neither titleRe nor appNameRe protects every window of
+ * the apps it names ('.*'). The web browsers ride as the last blocked-app rule.
+ */
+export function guardSpec(config = {}) {
+  const guards = config.guards || {};
+  const list = (value) => (Array.isArray(value) ? value : []);
+  const browsers = browserGuardRule(config);
+  return {
+    blockedApps: [
+      ...list(guards.blockedApps).map((rule) => ({
+        id: rule.id, bundleIds: rule.bundleIds || [], bundlePrefixes: list(rule.bundlePrefixes),
+        nameRe: rule.nameRe || undefined, windowTitleRe: rule.windowTitleRe || undefined, reason: rule.reason || 'blocked',
+      })),
+      ...(browsers ? [browsers] : []),
+    ],
+    protectedWindows: list(guards.protectedWindows).map((rule) => ({
+      id: rule.id, bundleIds: rule.bundleIds || [], bundlePrefixes: list(rule.bundlePrefixes),
+      titleRe: rule.titleRe || (rule.appNameRe ? undefined : '.*'), appNameRe: rule.appNameRe || undefined,
+      reason: rule.reason || 'protected',
+    })),
+    secureField: guards.secureField !== false,
+    refuseWhenLocked: guards.refuseWhenLocked !== false,
+  };
+}
+
+/** A web browser by bundle id (browserGuardRule), else false. */
+export function isBrowserBundle(config = {}, bundleId = null) {
+  const rule = bundleId ? browserGuardRule(config) : null;
+  if (!rule) return false;
+  const id = String(bundleId).toLowerCase();
+  return rule.bundleIds.some((b) => b.toLowerCase() === id) || hasPrefix(id, rule.bundlePrefixes);
+}
+
+/**
+ * Node-side mirror of the helper's app blocklist (open/focus requests are
+ * refused before reaching it). The web browsers match by bundle id only; a
+ * name ("Google Chrome") is refused by the helper once it resolves the app.
+ */
+export function blockedAppRule(config = {}, { bundleId = null, name = null } = {}) {
+  const appName = name == null ? null : String(name).normalize('NFC');
+  for (const rule of config.guards?.blockedApps || []) {
+    if (bundleId && (rule.bundleIds || []).some((id) => id.toLowerCase() === String(bundleId).toLowerCase())) return rule;
+    if (bundleId && hasPrefix(bundleId, rule.bundlePrefixes)) return rule;
+    if (appName && rule.nameRe) { try { if (new RegExp(String(rule.nameRe).normalize('NFC'), 'i').test(appName)) return rule; } catch {} }
+    if (appName && (rule.bundleIds || []).some((id) => id.toLowerCase().endsWith(`.${appName.toLowerCase().replace(/\s+/g, '')}`))) return rule;
+  }
+  return isBrowserBundle(config, bundleId) ? browserGuardRule(config) : null;
+}
+
+function targetLabel(probe = {}) {
+  return [probe.title, probe.description, probe.valuePreview, probe.role === 'AXButton' ? 'button' : null].filter(Boolean).join(' ').slice(0, 200);
+}
+
+/**
+ * Non-blocking warnings for one action.
+ * @param {object} ctx { action, text, probe, config, lexicon: { lexiconClass, addressesAgent } }
+ */
+export function actionWarnings({ action = '', text = '', probe = null, config = {}, lexicon = null } = {}) {
+  const warnings = [];
+  const guards = config.guards || {};
+  if (guards.moneyWarnings !== false) {
+    if ((action === 'type' || action === 'key') && looksLikeCardNumber(text)) {
+      warnings.push({ kind: 'card-number', label: 'The typed text looks like a card number. Only continue if the user explicitly asked for this payment.' });
+    }
+    const label = probe ? targetLabel(probe) : '';
+    if (label && lexicon?.lexiconClass) {
+      let cls = null;
+      try { cls = lexicon.lexiconClass(label); } catch {}
+      if (cls === 'payment') warnings.push({ kind: 'payment', label: `"${label.slice(0, 60)}" looks like a payment control. Never spend money unless the user explicitly asked.` });
+      else if (cls === 'publish') warnings.push({ kind: 'publish', label: `"${label.slice(0, 60)}" looks like a publish/send control. Make sure the user asked for this.` });
+      else if (cls === 'destructive') warnings.push({ kind: 'destructive', label: `"${label.slice(0, 60)}" looks destructive (delete/remove). Make sure the user asked for this.` });
+    }
+  }
+  return warnings;
+}
+
+/** Flag accessibility text that addresses the agent (prompt injection). */
+export function addressesAgentText(text, lexicon = null) {
+  if (!text || !lexicon?.addressesAgent) return false;
+  try { return !!lexicon.addressesAgent(String(text)); } catch { return false; }
+}