npm - @claudecollab/cli - Versions diffs - 0.1.0 - Mend

@claudecollab/cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/LICENSE +21 -0
package/README.md +109 -0
package/package.json +36 -0
package/packages/cli/bin/claude-share.js +1319 -0
package/packages/cli/package.json +15 -0
package/packages/cli/src/brain/card.js +157 -0
package/packages/cli/src/brain/commands.js +122 -0
package/packages/cli/src/brain/drafts.js +557 -0
package/packages/cli/src/brain/gate.js +134 -0
package/packages/cli/src/brain/knocks.js +27 -0
package/packages/cli/src/brain/log.js +123 -0
package/packages/cli/src/brain/queue.js +81 -0
package/packages/cli/src/brain/state.js +245 -0
package/packages/cli/src/hooks.js +243 -0
package/packages/cli/src/invite.js +43 -0
package/packages/cli/src/known-relays.js +66 -0
package/packages/cli/src/pty.js +175 -0
package/packages/cli/src/relay-client.js +271 -0
package/packages/cli/src/renderer.js +230 -0
package/packages/cli/src/screen-snapshot.js +139 -0
package/packages/cli/src/term-chatter.js +89 -0
package/packages/relay/auth.js +18 -0
package/packages/relay/bin/serve.js +73 -0
package/packages/relay/names.js +27 -0
package/packages/relay/package.json +13 -0
package/packages/relay/public/client.js +1553 -0
package/packages/relay/public/index.html +110 -0
package/packages/relay/public/style.css +952 -0
package/packages/relay/rooms.js +149 -0
package/packages/relay/server.js +652 -0
package/packages/relay/web.js +334 -0
package/packages/relay/wordlists.js +38 -0
package/packages/shared/package.json +8 -0
package/packages/shared/protocol.js +189 -0

package/packages/relay/web.js ADDED Viewed

@@ -0,0 +1,334 @@
+// The relay's web door — a browser front-end onto the exact same room machinery
+// the ssh guest door uses (spec v2: "the browser is the one multiplayer surface
+// for everyone, host included"). startRelay() starts this when opts.webPort is set.
+//
+// Two jobs, both dumb on purpose (the brain stays in the host CLI):
+//
+//   1. HTTP static: GET / and GET /<roomCode> serve packages/relay/public/index.html
+//      (the SPA entry); GET /<file>.<ext> (e.g. /client.js, /style.css) serves that
+//      file from the public dir; GET /assets/* serves the vendored @xterm/xterm files
+//      straight out of node_modules. All three are path-traversal safe (resolved and
+//      pinned inside their base dir).
+//
+//   2. WS /ws?room=<code>&name=<name>&token=<browser-token>  — a web participant.
+//      It knocks / admits / bans / caps through the SAME registry + room state as an
+//      ssh guest; the only difference is the transport:
+//        • fp = 'web:' + token          (localStorage token → returning identity)
+//        • host tab: /ws?...&host=<hostToken>  → fp = 'webhost:' + hostToken. The
+//          relay makes NO trust decision — it just forwards that fp in the knock;
+//          the brain auto-admits when it matches the token it generated (role host).
+//        • relay→browser  BINARY frame = screen bytes (feed to xterm)
+//                         TEXT frame   = JSON protocol ({t:'state'|'joined'|'error'})
+//        • browser→relay  TEXT frame   = JSON {t:'key'|'resize'|'pointer'|'ui', …};
+//          the relay STAMPS the sender id (never trusts a browser-supplied one) and
+//          forwards to the host, so the role gate in the brain still governs.
+import http from 'node:http';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { WebSocketServer } from 'ws';
+import { TYPES, encode, validate } from '../shared/protocol.js';
+import { sanitizeName } from './names.js';
+import { secretsMatch } from './auth.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC_DIR = path.join(here, 'public');
+const INDEX_HTML = path.join(PUBLIC_DIR, 'index.html');
+// Resolve the vendored xterm package dir through node resolution so monorepo
+// hoisting doesn't matter. `/assets/<rest>` maps to `<xtermDir>/<rest>`.
+const require = createRequire(import.meta.url);
+const XTERM_DIR = path.dirname(require.resolve('@xterm/xterm/package.json'));
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+};
+const contentType = (p) => CONTENT_TYPES[path.extname(p).toLowerCase()] ?? 'application/octet-stream';
+// Served when public/index.html doesn't exist yet (T3 owns the real client).
+const FALLBACK_INDEX =
+  '<!doctype html><meta charset="utf-8"><title>claudecollab</title>' +
+  '<body style="font:16px system-ui;margin:3rem;max-width:40rem">' +
+  '<h1>claudecollab</h1><p>the web client is not built yet.</p></body>';
+function isObj(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+// ---- ws send helpers (fail-soft; a closed socket must never throw) -----------
+function wsSendBinary(ws, data) {
+  if (ws.readyState !== ws.OPEN) return;
+  try {
+    ws.send(Buffer.isBuffer(data) ? data : Buffer.from(String(data), 'utf8'), { binary: true });
+  } catch {
+    /* socket already gone */
+  }
+}
+function wsSendText(ws, str) {
+  if (ws.readyState !== ws.OPEN) return;
+  try {
+    ws.send(typeof str === 'string' ? str : JSON.stringify(str));
+  } catch {
+    /* socket already gone */
+  }
+}
+function wsClose(ws) {
+  try {
+    ws.close();
+  } catch {
+    /* already closing */
+  }
+}
+const sendErr = (ws, reason) => wsSendText(ws, JSON.stringify({ t: 'error', reason }));
+/**
+ * Start the HTTP + WebSocket web door. Shares the live routing state and the
+ * registry with the ssh relay so web participants are real room members.
+ *
+ * @param {object} ctx
+ * @param {number} ctx.port                 listen port (0 ⇒ ephemeral; spec prod: 443)
+ * @param {string} ctx.host                 bind address
+ * @param {Map<string,object>} ctx.live     code -> live room (shared with server.js)
+ * @param {object} ctx.registry             the shared room registry (cap/ban/knock-limit)
+ * @param {number} ctx.knockTimeoutMs       waiting-screen timeout
+ * @param {(rec:object)=>void} ctx.onGuestGone  shared guest-teardown (frees seat, LEFTs the host)
+ * @param {(stream:any,data:any)=>void} ctx.safeWrite  shared fail-soft writer (to the host stream)
+ * @returns {Promise<{close():void, port:number, address:object}>}
+ */
+export function startWebDoor(ctx) {
+  const { port = 0, host = '127.0.0.1', live, registry, knockTimeoutMs, onGuestGone, safeWrite } = ctx;
+  // ---- HTTP: index (SPA-style, room code in the path) + vendored xterm assets
+  function serveIndex(res) {
+    const s = createReadStream(INDEX_HTML);
+    s.on('open', () => {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      s.pipe(res);
+    });
+    s.on('error', () => {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(FALLBACK_INDEX);
+    });
+  }
+  // Serve a file from a fixed base dir, path-traversal safe. `rest` begins with '/';
+  // any '../' resolves out and fails the prefix check, so a request can never escape
+  // the base. Shared by the vendored xterm assets and the public client files.
+  async function serveFrom(baseDir, rest, res) {
+    const target = path.resolve(baseDir, '.' + rest);
+    if (target !== baseDir && !target.startsWith(baseDir + path.sep)) {
+      res.writeHead(403, { 'content-type': 'text/plain' });
+      return res.end('forbidden');
+    }
+    let st;
+    try {
+      st = await stat(target);
+    } catch {
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      return res.end('not found');
+    }
+    if (!st.isFile()) {
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      return res.end('not found');
+    }
+    // no-cache: the browser must revalidate on every load, or a tab keeps running a
+    // stale client (style/logic) after the host updates — confusing mid-iteration.
+    res.writeHead(200, {
+      'content-type': contentType(target),
+      'content-length': st.size,
+      'cache-control': 'no-cache',
+    });
+    createReadStream(target).pipe(res);
+  }
+  const serveAsset = (rest, res) => serveFrom(XTERM_DIR, rest, res);
+  const servePublic = (rest, res) => serveFrom(PUBLIC_DIR, rest, res);
+  const server = http.createServer((req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { 'content-type': 'text/plain' });
+      return res.end('method not allowed');
+    }
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+    } catch {
+      res.writeHead(400, { 'content-type': 'text/plain' });
+      return res.end('bad request');
+    }
+    if (pathname.startsWith('/assets/')) return void serveAsset(pathname.slice('/assets'.length), res);
+    // A single-segment path with a file extension (e.g. /client.js, /style.css,
+    // /favicon.ico) → a static file from the public dir. Room codes have no dot, so
+    // they never match here and fall through to the SPA below.
+    if (pathname.indexOf('/', 1) === -1 && path.extname(pathname)) return void servePublic(pathname, res);
+    // '/' or a single-segment path (a room code, e.g. /brave-otter) → the SPA.
+    if (pathname === '/' || (pathname.indexOf('/', 1) === -1 && pathname.length > 1)) return serveIndex(res);
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('not found');
+  });
+  // ---- WS: web participants, on the shared room machinery ---------------------
+  const wss = new WebSocketServer({ noServer: true });
+  server.on('upgrade', (req, socket, head) => {
+    let url;
+    try {
+      url = new URL(req.url, 'http://localhost');
+    } catch {
+      return socket.destroy();
+    }
+    if (url.pathname !== '/ws') return socket.destroy();
+    wss.handleUpgrade(req, socket, head, (ws) => onConnect(ws, url, req));
+  });
+  function onConnect(ws, url, req) {
+    ws.on('error', () => {}); // client resets are routine; never crash the relay
+    const q = url.searchParams;
+    const code = q.get('room');
+    const hostToken = q.get('host');
+    const isHostTab = !!hostToken;
+    // Identity: the host tab carries the host token; a guest carries its browser
+    // token (session-only if absent). The relay makes no trust call — the brain does.
+    const fp = isHostTab ? 'webhost:' + hostToken : 'web:' + (q.get('token') || randomUUID());
+    // Printable-ASCII only, same as the ssh door: `?name=` is an untrusted URL param,
+    // and the host writes it verbatim to its terminal / log / session.md and mirrors
+    // it to every ssh guest — raw ESC/OSC/BEL bytes here would be escape injection.
+    const name = sanitizeName(q.get('name'), isHostTab ? 'host' : 'guest');
+    const ip = req.socket.remoteAddress || 'unknown';
+    // Same gate as the ssh door (spec: respect bans/lockouts/caps identically).
+    const room = code ? live.get(code) : null;
+    if (!code || !room || !registry.get(code)) return void (sendErr(ws, 'no-room'), wsClose(ws));
+    if (!room.hostPresent) return void (sendErr(ws, 'host-gone'), wsClose(ws));
+    if (fp && registry.get(code).banned.has(fp)) return void (sendErr(ws, 'banned'), wsClose(ws));
+    if (!registry.tryKnock(code, ip)) return void (sendErr(ws, 'lockout'), wsClose(ws));
+    // Room password pre-gate (mirrors the ssh door's prompt). Host tabs are
+    // exempt: their credential is the host token the brain itself minted — and a
+    // forged `?host=` gains nothing, it just lands as an ordinary pending knock
+    // the host will see and deny. Wrong guesses already burned a tryKnock slot
+    // above, so brute force hits the per-ip lockout fast.
+    if (!isHostTab && room.pass && !secretsMatch(q.get('pass') ?? '', room.pass)) {
+      return void (sendErr(ws, 'password'), wsClose(ws));
+    }
+    const rec = {
+      id: randomUUID(),
+      code,
+      kind: 'web', // marks this rec for the host channel's web-only branches (state/joined)
+      ws,
+      fp,
+      name,
+      phase: 'knocking', // web skips the ssh name prompt: name arrives in the query
+      cols: 80, // spec floor; refined by the browser's first {t:'resize'}
+      rows: 24,
+      knockTimer: null,
+      announced: false,
+      gone: false,
+      // Adapters so the shared host-channel handlers (SCREEN/TO/DENY/DROP/close…)
+      // treat a web rec exactly like an ssh one: byte writes become binary frames.
+      stream: { write: (d) => wsSendBinary(ws, d), end: () => wsClose(ws) },
+      conn: { end: () => wsClose(ws) },
+      sendText: (s) => wsSendText(ws, s), // STATE + the 'joined' signal go as text
+    };
+    room.pending.set(rec.id, rec);
+    // Knock the host (identical shape to the ssh door). A returning token carries
+    // its prior name in `seen`; brand-new ⇒ null.
+    const priorName = room.seen.get(fp);
+    const seen = priorName !== undefined ? priorName : null;
+    room.seen.set(fp, name);
+    rec.announced = true;
+    safeWrite(room.hostStream, encode({ t: TYPES.KNOCK, id: rec.id, name: rec.name, fp: rec.fp, seen }));
+    rec.knockTimer = setTimeout(() => {
+      if (rec.gone) return;
+      sendErr(ws, 'timeout');
+      wsClose(ws); // 'close' → onGuestGone: drops the seat, LEFTs the host
+    }, knockTimeoutMs);
+    rec.knockTimer.unref?.();
+    ws.on('message', (data, isBinary) => {
+      if (isBinary) return; // browsers only send JSON text; screen flows one way
+      if (rec.phase !== 'live') return; // ignore input until admitted (ssh parity)
+      const r = live.get(rec.code);
+      if (!r || !r.hostPresent || !r.guests.has(rec.id)) return;
+      let msg;
+      try {
+        msg = JSON.parse(data.toString('utf8'));
+      } catch {
+        return;
+      }
+      if (!isObj(msg)) return;
+      // Build the host-bound message with the relay-stamped id (never the browser's).
+      let out = null;
+      switch (msg.t) {
+        case 'key':
+          out = { t: TYPES.KEY, id: rec.id, data: msg.data };
+          break;
+        case 'resize':
+          if (Number.isFinite(msg.cols) && Number.isFinite(msg.rows)) {
+            rec.cols = msg.cols;
+            rec.rows = msg.rows;
+          }
+          out = { t: TYPES.RESIZE, id: rec.id, cols: msg.cols, rows: msg.rows };
+          break;
+        case 'pointer':
+          out = { t: TYPES.POINTER, id: rec.id, x: msg.x, y: msg.y };
+          break;
+        case 'ui':
+          out = { t: TYPES.UI, id: rec.id, action: msg.action };
+          break;
+        default:
+          return;
+      }
+      if (validate(out)) safeWrite(r.hostStream, encode(out)); // fail closed on anything malformed
+    });
+    ws.on('close', () => onGuestGone(rec));
+  }
+  function close() {
+    for (const ws of wss.clients) {
+      try {
+        ws.terminate();
+      } catch {
+        /* already gone */
+      }
+    }
+    try {
+      wss.close();
+    } catch {
+      /* not started */
+    }
+    try {
+      server.close();
+    } catch {
+      /* not listening */
+    }
+  }
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, function () {
+      server.removeListener('error', reject);
+      server.on('error', () => {}); // post-listen errors shouldn't crash the process
+      resolve({ close, port: this.address().port, address: this.address() });
+    });
+  });
+}

package/packages/relay/wordlists.js ADDED Viewed

@@ -0,0 +1,38 @@
+// Room-code vocabulary: speakable, friendly, lowercase single words.
+// Codes read as `adjective-animal` (e.g. brave-otter). ~100+ of each keeps the
+// 2-word space >10k combinations, so collisions at creation are rare.
+export const adjectives = [
+  'brave', 'calm', 'clever', 'bright', 'bold', 'gentle', 'happy', 'jolly',
+  'kind', 'lively', 'merry', 'nimble', 'proud', 'quiet', 'rapid', 'shiny',
+  'smooth', 'swift', 'witty', 'zesty', 'amber', 'azure', 'cosmic', 'crimson',
+  'dapper', 'eager', 'fancy', 'fuzzy', 'golden', 'grassy', 'husky', 'icy',
+  'ivory', 'jade', 'keen', 'lucky', 'mellow', 'misty', 'mighty', 'noble',
+  'olive', 'plucky', 'prime', 'royal', 'rustic', 'sandy', 'silver', 'snowy',
+  'solar', 'spry', 'stormy', 'sunny', 'teal', 'tidy', 'tiny', 'vivid',
+  'wavy', 'wise', 'zippy', 'breezy', 'cheery', 'cozy', 'crisp', 'curly',
+  'dandy', 'dewy', 'dreamy', 'dusky', 'earthy', 'feisty', 'fleet', 'frosty',
+  'glossy', 'hazy', 'humble', 'jazzy', 'leafy', 'lunar', 'minty', 'mossy',
+  'peppy', 'perky', 'quirky', 'rosy', 'salty', 'scarlet', 'shady', 'sleek',
+  'spicy', 'starry', 'sturdy', 'sylvan', 'thrifty', 'upbeat', 'velvet',
+  'woolly', 'zealous', 'gleaming', 'radiant', 'spirited', 'cheerful',
+  'dazzling', 'graceful', 'playful', 'twinkly',
+];
+export const animals = [
+  'otter', 'falcon', 'badger', 'beaver', 'bison', 'cheetah', 'cobra', 'condor',
+  'coyote', 'cricket', 'dolphin', 'dingo', 'eagle', 'egret', 'ferret', 'finch',
+  'gecko', 'gibbon', 'giraffe', 'goose', 'gopher', 'heron', 'hornet', 'ibex',
+  'iguana', 'jackal', 'jaguar', 'kestrel', 'koala', 'lemur', 'leopard', 'lizard',
+  'llama', 'lynx', 'magpie', 'marmot', 'meerkat', 'mole', 'moose', 'moth',
+  'narwhal', 'newt', 'ocelot', 'octopus', 'orca', 'osprey', 'panda', 'panther',
+  'parrot', 'pelican', 'penguin', 'pheasant', 'pigeon', 'puffin', 'python',
+  'quail', 'rabbit', 'raccoon', 'raven', 'robin', 'salmon', 'seal', 'shark',
+  'sparrow', 'spider', 'squid', 'stoat', 'stork', 'swan', 'tapir', 'tiger',
+  'toucan', 'turtle', 'urchin', 'vulture', 'walrus', 'weasel', 'whale', 'wolf',
+  'wombat', 'wren', 'yak', 'zebra', 'alpaca', 'antelope', 'armadillo', 'buffalo',
+  'camel', 'caribou', 'chipmunk', 'cougar', 'crane', 'dove', 'elk', 'gazelle',
+  'hare', 'hedgehog', 'hamster', 'kangaroo', 'kingfisher', 'mackerel', 'manatee',
+  'mongoose', 'mustang', 'platypus', 'quokka', 'reindeer', 'salamander',
+  'starling', 'terrier',
+];

package/packages/shared/package.json ADDED Viewed

@@ -0,0 +1,8 @@
+{
+  "name": "@claude-share/shared",
+  "version": "0.0.0",
+  "license": "MIT",
+  "private": true,
+  "type": "module",
+  "main": "protocol.js"
+}

package/packages/shared/protocol.js ADDED Viewed

@@ -0,0 +1,189 @@
+// claude-share wire protocol: JSON-lines over the host's ssh channel to the relay.
+// Guests speak no protocol — they exchange raw terminal bytes. Only the host<->relay
+// control channel uses these messages.
+/** Canonical message-type strings (the `t` field of every message). */
+export const TYPES = Object.freeze({
+  HELLO: 'hello', // host->relay: {t:'hello', want:'room', secret?, pass?} — new room (secret = relay
+  //   room-creation credential; pass = optional per-room JOIN password guests must present)
+  RECLAIM: 'reclaim', // host->relay: {t:'reclaim', code}           — take back an existing room after a drop
+  ROOM: 'room', // relay->host: {t:'room', code}                    — room granted (create OR reclaim)
+  GONE: 'gone', // relay->host: {t:'gone', code}                    — reclaim refused (expired / wrong key)
+  REFUSED: 'refused', // relay->host: {t:'refused', reason}         — HELLO rejected ('secret' = bad/missing room secret)
+  KNOCK: 'knock', // relay->host: {t:'knock', id, name, fp, seen}
+  ADMIT: 'admit', // host->relay: {t:'admit', id}
+  DENY: 'deny', // host->relay: {t:'deny', id}
+  JOINED: 'joined', // relay->host: {t:'joined', id}
+  LEFT: 'left', // relay->host: {t:'left', id}
+  KEY: 'key', // relay->host: {t:'key', id, data}   (guest keystrokes, base64)
+  RESIZE: 'resize', // relay->host: {t:'resize', id, cols, rows}
+  SCREEN: 'screen', // host->relay: {t:'screen', data}  (broadcast frame, base64)
+  TO: 'to', // host->relay: {t:'to', id, data}   (one guest only, base64)
+  DROP: 'drop', // host->relay: {t:'drop', id, ban}
+  END: 'end', // host->relay: {t:'end'}
+  // ── overlay-state channel (browser multiplayer surface) ────────────────────
+  // The browser is the multiplayer surface for everyone (host included): a plain
+  // ssh guest still exchanges raw bytes, but a browser view renders a rich overlay
+  // from the host's snapshot and mails back pointer moves and button-driven commands.
+  STATE: 'state', // host->relay: {t:'state', data:{room, participants:[{id,name,role,color}],
+  //   drafts:<Drafts.snapshot()>, queue:[{n,author,text}], claudeState:'busy'|'idle'|'ask',
+  //   paused:bool, pointers:{id:{x,y,name,color}}, knocks:[{id,name,fp,seen}]}} — full
+  //   overlay snapshot, emitted on every brain change (throttled ≤1/50ms); the relay
+  //   fans it out to browser views. Knocks live IN the state (the host admits from the browser).
+  POINTER: 'pointer', // guest->host (relay stamps `id` = sender): {t:'pointer', id?, x, y}
+  //   x/y normalized 0..1 over the terminal canvas; the host rebroadcasts via state.pointers.
+  UI: 'ui', // guest->host (relay stamps `id` = sender): {t:'ui', id?, action}
+  //   action = {kind:'admit'|'deny', id} | {kind:'command', text}. The command text runs
+  //   through the existing parser AS that sender, so the role gate still applies.
+});
+/**
+ * Serialize a message to a newline-terminated JSON Buffer, ready to write to a stream.
+ * @param {object} obj
+ * @returns {Buffer}
+ */
+export function encode(obj) {
+  return Buffer.from(JSON.stringify(obj) + '\n');
+}
+// Newline-free buffer cap (10 MB). Real messages are tiny (a full-repaint screen
+// frame is a few KB of base64), so a partial line this large is a peer that
+// never terminates — a memory-exhaustion flood. We drop it rather than grow.
+const MAX_BUF = 10 * 1024 * 1024;
+/**
+ * Stateful, per-connection stream decoder. Feed it raw chunks (Buffer or string);
+ * it buffers partial lines and returns an array of parsed messages once each line
+ * is complete. One instance per ssh channel.
+ */
+export class Decoder {
+  #buf = '';
+  /**
+   * @param {Buffer|string} chunk
+   * @returns {object[]} messages completed by this chunk (possibly empty)
+   */
+  push(chunk) {
+    this.#buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    const out = [];
+    let nl;
+    while ((nl = this.#buf.indexOf('\n')) !== -1) {
+      const line = this.#buf.slice(0, nl);
+      this.#buf = this.#buf.slice(nl + 1);
+      if (line.trim() === '') continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        // Malformed line: drop it (spec: the relay and host drop anything that
+        // fails the check). A single unparseable line must never sever the
+        // connection or swallow the valid messages that follow it.
+      }
+    }
+    // Only a newline-free remainder is left now. If it has outgrown the cap, no
+    // terminator is coming — clear it so a peer can't exhaust memory.
+    if (this.#buf.length > MAX_BUF) this.#buf = '';
+    return out;
+  }
+}
+/**
+ * Stateless one-shot decode of a chunk that contains only complete lines
+ * (e.g. the output of `encode`, which always ends in a newline). A trailing
+ * partial line is ignored. For streaming input use a {@link Decoder}.
+ * @param {Buffer|string} chunk
+ * @returns {object[]}
+ */
+export function decode(chunk) {
+  return new Decoder().push(chunk);
+}
+const isStr = (v) => typeof v === 'string';
+const isNum = (v) => Number.isFinite(v);
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+// A {t:'ui'} action: a knock verdict (admit/deny, carrying the target knock id), a
+// roster action (role/kick, carrying the target PARTICIPANT id — not a @-mention, so
+// duplicate/space/unicode names can't mis-target), or a button-driven command (command
+// text). Anything else is rejected — this is the boundary that lets a browser button
+// drive the host, so it fails closed.
+function isUiAction(a) {
+  if (!isObj(a)) return false;
+  if (a.kind === 'admit' || a.kind === 'deny' || a.kind === 'kick') return isStr(a.id);
+  if (a.kind === 'role') return isStr(a.id) && isStr(a.role);
+  if (a.kind === 'command') return isStr(a.text);
+  if (a.kind === 'caret') return isStr(a.id) && isNum(a.offset); // click into a draft
+  if (a.kind === 'delrange') return isStr(a.id) && isNum(a.start) && isNum(a.end); // delete a selection
+  if (a.kind === 'deldraft') return isStr(a.id); // delete a whole draft box
+  if (a.kind === 'place') return isStr(a.id) && (a.home === true || (isNum(a.x) && isNum(a.y))); // move/resize a draft (shared)
+  if (a.kind === 'unqueue') return isNum(a.n); // pull a queued prompt back into a draft
+  if (a.kind === 'scroll') return isNum(a.lines); // wheel over the mirror → Claude's transcript scroll
+  if (a.kind === 'resync') return true; // host: force claude-state idle (missed hook)
+  return false;
+}
+/**
+ * Shallow structural validation of a decoded message. Returns true only for a
+ * known type whose required fields are present and correctly typed. The relay
+ * and host drop anything that fails this check.
+ * @param {unknown} obj
+ * @returns {boolean}
+ */
+export function validate(obj) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  switch (obj.t) {
+    case TYPES.HELLO:
+      // secret (optional): the relay-wide room-creation credential. Compared on
+      // the relay when configured; a plain relay ignores it.
+      // pass (optional): a join password for THIS room — the relay stores it and
+      // pre-gates every guest (ssh prompt / web form) before the knock is sent.
+      return (
+        obj.want === 'room' &&
+        (obj.secret === undefined || isStr(obj.secret)) &&
+        (obj.pass === undefined || isStr(obj.pass))
+      );
+    case TYPES.REFUSED:
+      return isStr(obj.reason);
+    case TYPES.ROOM:
+      // webUrl (optional): a deployed relay's public browser base URL — the host
+      // builds its printed/copied links from it instead of ssh-host:webPort.
+      return isStr(obj.code) && (obj.webUrl === undefined || isStr(obj.webUrl));
+    case TYPES.RECLAIM:
+    case TYPES.GONE:
+      return isStr(obj.code);
+    case TYPES.KNOCK:
+      return (
+        isStr(obj.id) &&
+        isStr(obj.name) &&
+        isStr(obj.fp) &&
+        (isStr(obj.seen) || typeof obj.seen === 'boolean' || obj.seen === null)
+      );
+    case TYPES.ADMIT:
+    case TYPES.DENY:
+    case TYPES.JOINED:
+    case TYPES.LEFT:
+      return isStr(obj.id);
+    case TYPES.KEY:
+    case TYPES.TO:
+      return isStr(obj.id) && isStr(obj.data);
+    case TYPES.RESIZE:
+      return isStr(obj.id) && isNum(obj.cols) && isNum(obj.rows);
+    case TYPES.SCREEN:
+      return isStr(obj.data);
+    case TYPES.DROP:
+      return isStr(obj.id) && typeof obj.ban === 'boolean';
+    case TYPES.END:
+      return true;
+    // Overlay channel. Shallow, like the rest: `data` need only be a plain object
+    // (browser views read it defensively). pointer/ui carry an optional sender `id`
+    // the relay stamps on the guest→host hop; guest→relay forms omit it.
+    case TYPES.STATE:
+      return isObj(obj.data);
+    case TYPES.POINTER:
+      return isNum(obj.x) && isNum(obj.y) && (obj.id === undefined || isStr(obj.id));
+    case TYPES.UI:
+      return (obj.id === undefined || isStr(obj.id)) && isUiAction(obj.action);
+    default:
+      return false;
+  }
+}