@joystack/cli 0.1.50 → 0.1.51

package/lib/relay/relay.mjs

@@ -0,0 +1,300 @@
+// The relay's hub, inside the dev server: events from a page the server
+// serves, or from the agent, passed on to every other place something
+// listens. The browser half is shared/ui/relay/relay.js (its README is the
+// contract both halves keep).
+//
+//   POST /__joystack/relay                  publish { id?, name, data, image?, client? }
+//   GET  /__joystack/relay/stream?listen=…  SSE: `hello` (this client's id, what the
+//                                           other places listen for, the agent), then
+//                                           `listens`, `agent` and `event` frames
+//   GET  /__joystack/relay/status           { agent }, for `joystack assets`' warning
+//
+// Who may do what: a page this server served may publish (same origin), and
+// the creator's own pages (this machine, or the owner's live link in the
+// maker: `fromCreator`) may also listen; a phone on the wifi or a --share
+// tester publishes with `from.creator` false and a picture refused, and
+// cannot listen. The agent speaks with the bearer token the server writes to
+// .joystack/relay/.connection-<port> (connection.mjs), from loopback and never
+// from a browser, and is stamped `from.agent`. `from` is stamped here and
+// never taken from the sender.
+//
+// An event goes only where something listens. Each stream names what its
+// page listens for; the hub keeps the union of what the OTHER places listen
+// for per client and streams it, so a window posts only what would reach
+// someone. The hub's own listeners (the laptop conversation, conversation.mjs,
+// when an agent session started the server; a `joystack relay tail`) are in
+// that union like any page.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { sessionAlive } from '../agent-session.mjs';
+import { removeConnection, writeConnection } from './connection.mjs';
+import { createConversation, newToken } from './conversation.mjs';
+
+export const RELAY_PATH = '/__joystack/relay';
+// What one publish may weigh: a picture rides only from the creator's
+// browser, so its cap is larger; anyone else sends small JSON only.
+export const MAX_BYTES = 2 * 1024 * 1024;
+export const LOCAL_MAX_BYTES = 8 * 1024 * 1024;
+const MAX_LISTENS = 32;
+const AGENT_POLL_MS = 3000;
+const NAME_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
+const PATTERN_RE = /^[a-z0-9*][a-z0-9*-]*(\.[a-z0-9*][a-z0-9*-]*)*$/;
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const PNG_PREFIX = 'data:image/png;base64,';
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+// A pattern compiled once, when a listen is registered: the hub tests every
+// listen of every client against every event, so each pattern is a RegExp
+// held with its listen rather than split again per event. `*` stands for one
+// segment; alone it matches every name.
+export function matcher(pattern) {
+  if (pattern === '*') return /^[a-z0-9.-]+$/;
+  const segs = String(pattern).split('.').map((seg) => (seg === '*' ? '[a-z0-9-]+' : seg.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')));
+  return new RegExp(`^${segs.join('\\.')}$`);
+}
+const withMatcher = (listen) => ({ ...listen, re: matcher(listen.pattern) });
+
+const json = (res, status, body, extra = {}) => {
+  const buf = Buffer.from(JSON.stringify(body));
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': buf.length, 'Cache-Control': 'no-store', ...extra });
+  res.end(buf);
+};
+const text = (res, status, body, extra = {}) => {
+  res.writeHead(status, { 'Content-Type': 'text/plain', ...extra });
+  res.end(body);
+};
+
+// The listen list a stream asked for: `[[pattern, image], …]` as JSON.
+function parseListens(raw) {
+  let list;
+  try { list = JSON.parse(raw ?? '[]'); } catch { return null; }
+  if (!Array.isArray(list) || list.length > MAX_LISTENS) return null;
+  const out = [];
+  for (const item of list) {
+    const [pattern, image] = Array.isArray(item) ? item : [item, false];
+    if (typeof pattern !== 'string' || !PATTERN_RE.test(pattern)) return null;
+    out.push(withMatcher({ pattern, image: image === true }));
+  }
+  return out;
+}
+
+// The agent's credential: a bearer token from a process on this machine,
+// never a browser (which always sends Origin on a cross-origin request and
+// cannot set this header from a page the server did not serve). 'agent'
+// when it is the server's token, 'refused' when a bearer was offered and is
+// not, null when none was offered.
+function bearer(req, token) {
+  const header = String(req.headers.authorization ?? '');
+  if (!header.startsWith('Bearer ')) return null;
+  const supplied = Buffer.from(header.slice(7));
+  const expected = Buffer.from(token);
+  const ok = LOOPBACK.has(req.socket.remoteAddress) && !req.headers.origin
+    && supplied.length === expected.length && timingSafeEqual(supplied, expected);
+  return ok ? 'agent' : 'refused';
+}
+
+// The path of the page that published, from the request's Referer; null
+// for the agent, or when the browser sent none.
+function pageOf(req) {
+  try {
+    const u = new URL(String(req.headers.referer ?? ''));
+    return u.pathname;
+  } catch { return null; }
+}
+
+function readBody(req, res, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let size = 0;
+    let overflowed = false;
+    req.on('data', (chunk) => {
+      if (overflowed) return; // draining the rest so the client can read the 413
+      size += chunk.length;
+      if (size > maxBytes) {
+        overflowed = true;
+        chunks.length = 0;
+        text(res, 413, `event too large (max ${maxBytes} bytes)`, { Connection: 'close' });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(overflowed ? null : Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+// What a publish asked for, checked: `{ error }` with the words for a 400,
+// or `{ name, data, image, id, skip }`. A picture is a PNG data URL and only
+// from the creator's browser; an id the sender chose is kept when it is one
+// the hub would have made.
+function parseEvent(raw, creator) {
+  let body;
+  try { body = JSON.parse(raw); } catch { return { error: 'body must be JSON' }; }
+  const name = body?.name;
+  if (typeof name !== 'string' || !NAME_RE.test(name)) return { error: 'an event is named <publisher>.<what>' };
+  const { image } = body;
+  if (image !== undefined && (typeof image !== 'string' || !image.startsWith(PNG_PREFIX))) return { error: 'image must be a PNG data URL' };
+  if (image !== undefined && !creator) return { error: 'only the creator\'s own browser can attach a picture' };
+  return {
+    name,
+    data: body.data === undefined ? null : body.data,
+    image,
+    id: typeof body.id === 'string' && ID_RE.test(body.id) ? body.id : randomBytes(4).toString('hex'),
+    skip: typeof body.client === 'string' ? body.client : null,
+  };
+}
+
+export function createRelay({
+  projectDir, agentSession = null, log = () => {}, cliBin = 'joystack',
+  // The dev server's own trust checks (static-server.mjs): whether a request
+  // came from a page this server served, and from the creator's own browser.
+  sameOrigin = () => true, fromCreator = () => true,
+}) {
+  const token = newToken();
+  const clients = new Set();   // { id, res, listens, agent }
+  const own = [];              // the hub's own listeners: { pattern, image, deliver }
+  if (agentSession) own.push(withMatcher(createConversation({ projectDir, agentSession, log, cliBin })));
+  let port = null;
+  let agentTimer = null;
+  let lastAgent = null;
+
+  const agentNow = () => (sessionAlive(agentSession) ? agentSession.agent : null);
+  const send = (client, frame) => { try { client.res.write(`data: ${JSON.stringify(frame)}\n\n`); } catch { /* gone */ } };
+
+  // What everyone but `client` listens for, one entry per pattern, `image`
+  // when any of them asked for the picture.
+  function othersFor(client) {
+    const union = new Map();
+    const add = ({ pattern, image }) => { union.set(pattern, { pattern, image: image || union.get(pattern)?.image || false }); };
+    for (const c of clients) if (c !== client) c.listens.forEach(add);
+    own.forEach(add);
+    return [...union.values()];
+  }
+  const broadcastListens = () => { for (const c of clients) send(c, { type: 'listens', others: othersFor(c) }); };
+
+  // The agent coming and going is a session file appearing or vanishing,
+  // which no event announces, so it is looked at every few seconds while a
+  // page is listening, and told only when it changes.
+  function watchAgent() {
+    if (agentTimer || !agentSession) return;
+    lastAgent = agentNow();
+    agentTimer = setInterval(() => {
+      if (!clients.size) { clearInterval(agentTimer); agentTimer = null; return; }
+      const now = agentNow();
+      if (now === lastAgent) return;
+      lastAgent = now;
+      for (const c of clients) send(c, { type: 'agent', agent: now });
+    }, AGENT_POLL_MS);
+    agentTimer.unref();
+  }
+
+  // Deliver a stamped event: to every client (but the one that published it)
+  // whose listens match, with the picture only to one that asked; and to the
+  // hub's own listeners. Resolves { delivered, agent }.
+  async function deliver(event, image, skip) {
+    let delivered = 0;
+    for (const c of clients) {
+      if (skip && c.id === skip) continue;
+      const hits = c.listens.filter((l) => l.re.test(event.name));
+      if (!hits.length) continue;
+      const wantsImage = hits.some((l) => l.image) && image !== undefined;
+      send(c, { type: 'event', event: wantsImage ? { ...event, image } : event });
+      delivered += 1;
+    }
+    let agent = false;
+    for (const l of own) {
+      if (!l.re.test(event.name)) continue;
+      try {
+        const out = await l.deliver(event, { image: l.image ? image : undefined });
+        if (out?.agent) agent = true;
+      } catch (err) {
+        log(`relay: a listener for ${l.pattern} failed (${err?.message ?? err})`);
+      }
+    }
+    return { delivered, agent };
+  }
+
+  async function handlePublish(req, res) {
+    if (req.method !== 'POST') return text(res, 405, 'POST only', { Allow: 'POST' });
+    const auth = bearer(req, token);
+    if (auth === 'refused') return json(res, 403, { error: 'only `joystack relay` on this machine may publish as the agent' });
+    const agent = auth === 'agent';
+    // Only a page this server itself served may publish: a hostile website
+    // in the creator's browser can fire a no-preflight POST at localhost, and
+    // what is published here reaches an AI agent as data from the game.
+    if (!agent && !sameOrigin(req)) return text(res, 403, 'cross-origin post rejected');
+    const creator = agent || fromCreator(req);
+    const raw = await readBody(req, res, creator ? LOCAL_MAX_BYTES : MAX_BYTES);
+    if (raw === null) return undefined;
+    const asked = parseEvent(raw, creator);
+    if (asked.error) return text(res, 400, asked.error);
+    const { name, data, image, id, skip } = asked;
+    const event = { id, name, at: new Date().toISOString(), from: { page: agent ? null : pageOf(req), creator, agent }, data };
+    const out = await deliver(event, image, skip);
+    const label = typeof data?.label === 'string' ? ` ${JSON.stringify(data.label.slice(0, 80))}` : '';
+    log(`relay: ${name}${label} → ${out.delivered} listener${out.delivered === 1 ? '' : 's'}${out.agent ? ', the agent woken' : ''}`);
+    return json(res, 200, { ok: true, id, delivered: out.delivered, agent: out.agent });
+  }
+
+  function handleStream(req, res, query) {
+    if (req.method !== 'GET') return text(res, 405, 'GET only', { Allow: 'GET' });
+    const auth = bearer(req, token);
+    if (auth === 'refused') return json(res, 403, { error: 'only `joystack relay` on this machine may listen as the agent' });
+    const agent = auth === 'agent';
+    // The stream carries what the creator's tools say and show, so only the
+    // creator's own pages may open one. A browser names where a request came
+    // from; a page from another site is refused even where CORS would stop
+    // it from reading the answer.
+    const site = req.headers['sec-fetch-site'];
+    const siteOk = site === undefined || site === 'same-origin' || site === 'none';
+    if (!agent && !(fromCreator(req) && sameOrigin(req) && siteOk)) return text(res, 403, 'the relay is the creator\'s own');
+    const listens = agent && !query.has('listen') ? [withMatcher({ pattern: '*', image: false })] : parseListens(query.get('listen'));
+    if (!listens) return text(res, 400, 'listen must be a JSON list of [pattern, image] pairs');
+    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+    res.write(':connected\n\n');
+    const client = { id: randomBytes(4).toString('hex'), res, listens, agent };
+    clients.add(client);
+    send(client, { type: 'hello', client: client.id, others: othersFor(client), agent: agentNow() });
+    broadcastListens();
+    watchAgent();
+    const keepalive = setInterval(() => res.write(':keepalive\n\n'), 10_000);
+    keepalive.unref();
+    res.on('close', () => {
+      clearInterval(keepalive);
+      clients.delete(client);
+      broadcastListens();
+    });
+    return undefined;
+  }
+
+  // Whether an agent session is connected. Only the creator may read it, as
+  // for the stream; the custom header forces a CORS preflight the server never
+  // grants, so no foreign page can read it.
+  function handleStatus(req, res) {
+    if (!fromCreator(req) || !sameOrigin(req) || req.headers['x-joystack-agent-ui'] !== '1') return text(res, 403, 'dev tools only');
+    return json(res, 200, { agent: agentNow() });
+  }
+
+  return {
+    // Answers a request under RELAY_PATH; anything else is not the relay's.
+    handle(req, res, urlPath, query = new URLSearchParams()) {
+      if (urlPath === RELAY_PATH) return handlePublish(req, res).catch((err) => { log(`relay: ${err?.message ?? err}`); if (!res.headersSent) text(res, 500, '500'); });
+      if (urlPath === `${RELAY_PATH}/stream`) return handleStream(req, res, query);
+      if (urlPath === `${RELAY_PATH}/status`) return handleStatus(req, res);
+      return text(res, 404, 'not found');
+    },
+    // The server is listening on `port`: write the agent's credential.
+    attach(listeningPort) {
+      port = listeningPort;
+      try { writeConnection(projectDir, port, token); } catch (err) { log(`relay: the agent cannot publish (${err?.message ?? err})`); }
+    },
+    agent: agentNow,
+    // For a test: what every other place listens for, as a fresh stream would be told.
+    others: () => othersFor(null),
+    close() {
+      if (agentTimer) clearInterval(agentTimer);
+      agentTimer = null;
+      for (const c of clients) { try { c.res.end(); } catch { /* gone */ } }
+      clients.clear();
+      if (port !== null) removeConnection(projectDir, port, token);
+    },
+  };
+}