leetcode-capture-helper 0.0.0-stage → 0.1.1

package/runtime/relay-server/panel-broker.js

@@ -0,0 +1,797 @@
+// LeetCode Capture - in-page tutor panel broker
+//
+// The companion (a separate local process) publishes tutor events here, and
+// the in-page panel (the extension's panel.js, running on leetcode.com)
+// streams them out over Server-Sent Events and posts typed messages back.
+// This module only brokers: it never calls an LLM, and it keeps everything in
+// memory (a bounded event buffer), so a relay restart simply starts the panel
+// transcript fresh. Sequence numbers restart at 1 with it, so every event
+// (and the status event) carries this run's random `epoch`: a panel that
+// reconnects with `?after=<seq>&epoch=<old>` gets the whole new buffer
+// instead of having it filtered against a counter from a previous run, and
+// it resets its own `lastSeq` when it sees a new epoch.
+//
+// Routes (all under /panel/):
+//   GET  /panel/events?after=<seq>  panel     SSE stream of tutor events (replays the buffer after <seq>)
+//   POST /panel/message             panel     a typed message for the tutor
+//   POST /panel/switch-profile      panel     { id }: the model switcher picked a saved model
+//   POST /panel/publish             companion one event, or { events: [...] }
+//   GET  /panel/inbox               companion SSE stream of the panel's typed messages
+//   POST /panel/drop-problem        companion { problemSlug }: forget that problem's buffered events
+//   POST /panel/trim-captures       companion { before, path }: drop the capture log's first `before` bytes
+//   POST /panel/activity            companion { busy }: the tutor is working on (or has queued) a turn
+//   POST /panel/rpc-result          companion { id, response }: the answer to a settings call
+//   POST /settings/rpc              options   { method, params }: a settings call for the companion
+//
+// A `config` event (which provider and model the tutor uses, never a key) is
+// not buffered with the conversation: the newest one is kept on its own and
+// sent to every panel that connects, after the replay and before `status`.
+//
+// POST /panel/switch-profile is the one settings call a panel (and so any
+// script on leetcode.com) can make: it goes to the companion as the rpc
+// `switchProfile` with nothing but the id, and the companion accepts only an
+// id it already has saved, which changes nothing but which saved model is in
+// use (see companion/settings-rpc.js). The answer carries only whether it
+// worked, a reason and the non-secret summary of the model now in use.
+//
+// /settings/rpc is for the extension's own options page (extension/settings.js)
+// only: its Origin must be an extension origin (chrome-extension://<32 letters
+// a-p> or moz-extension://<uuid>), which a web page cannot send, plus the same
+// Host check. The call goes down the companion's inbox stream as
+// `{ type: "rpc", id, method, params }` and the request waits (up to
+// RPC_TIMEOUT_MS) for the companion's POST /panel/rpc-result. Settings carry
+// API keys, so leetcode.com (whose page scripts are not ours) is refused here
+// too. 503 when no companion is connected.
+//
+// Unlike /capture (which only ingests data, so a permissive CORS `*` is
+// harmless), these routes can READ tutor replies, which contain the student's
+// code, so any web page that could reach localhost must not be able to. Two
+// checks run on every request:
+//   - Host must be exactly the relay's own loopback address, which defeats DNS
+//     rebinding (an attacker's hostname resolving to 127.0.0.1 arrives with
+//     the attacker's Host header).
+//   - Origin must be absent or exactly https://leetcode.com. Browsers always
+//     send Origin on a CORS request and on any POST, and a page cannot forge
+//     it, so every other website is rejected.
+// The companion-only routes (publish, inbox, drop-problem, trim-captures, activity, rpc-result) additionally go through
+// companionOnlyRejection below. A missing Origin alone is NOT proof of the
+// companion: a page's `fetch(url, { mode: "no-cors" })` GET carries no Origin
+// either. What a browser page cannot do is add a custom header without a CORS
+// preflight, and that preflight carries an Origin and is refused (and even
+// leetcode.com's preflight is never told this header is allowed). So these
+// routes require COMPANION_HEADER, no Origin, and no cross-site Sec-Fetch-Site.
+// A script on leetcode.com can therefore only read events and post messages.
+//
+// Text in a typed message ends up printed in the student's terminal by the
+// companion, so C0/C1 control characters (escape sequences that could recolor
+// the terminal, retitle the window, or worse) and invisible bidi/zero-width
+// characters (which could disguise what the text says) are stripped at this
+// boundary.
+// The companion strips them again before printing anything untrusted.
+//
+// The number of open panel streams is capped, and only CORS-mode requests
+// count: a page's no-cors GET (or an <img> or <iframe>) to /panel/events has
+// no Origin, so without the Sec-Fetch-Mode check in handle() it could hold the
+// slots open, unread, and lock the real panel out.
+
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const PANEL_ORIGIN = "https://leetcode.com";
+// Sent by companion/panel-bridge.js on every companion-only request.
+const COMPANION_HEADER = "x-lc-companion";
+
+const MAX_BUFFERED_EVENTS = 2000;
+// A message may carry the live editor code (its `snapshot`), so the body cap
+// is sized for a long solution, not for the typed text alone. Real solutions
+// are a few KB; the snapshot's code and description caps (plus the typed
+// text) fit well under the body cap as plain JSON. extension/panel.js keeps
+// the same three numbers and leaves the snapshot out of a message rather than
+// send a body past them (never a truncated copy of the code).
+const MAX_MESSAGE_BYTES = 256 * 1024;
+const MAX_SNAPSHOT_CODE_CHARS = 100_000;
+const MAX_SNAPSHOT_DESCRIPTION_CHARS = 50_000;
+const MAX_PUBLISH_BYTES = 5 * 1024 * 1024;
+const MAX_TEXT_CHARS = 200_000;
+const MAX_MESSAGE_CHARS = 8000;
+const MAX_PANEL_STREAMS = 20;
+const MAX_OPEN_TURNS = 100;
+const HEARTBEAT_MS = 15_000;
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,199}$/i;
+
+// The options page's origin: Chrome's extension ids are 32 letters a-p,
+// Firefox's are a random UUID per install.
+const EXTENSION_ORIGIN_RE =
+  /^(chrome-extension:\/\/[a-p]{32}|moz-extension:\/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+// A connection test can wait on a slow model (settings-rpc.js gives it 90 s).
+const RPC_TIMEOUT_MS = 120_000;
+// A model switch answers only once the new model is in place, after the reply
+// already running (companion/settings-rpc.js), which may take minutes. The
+// panel waits 180 s (SWITCH_TIMEOUT_MS in extension/panel.js), so the relay
+// waits longer and the panel is always the one that gives up; a switch that
+// lands after that still reaches the panel as the companion's next config
+// event, which names the active profile.
+const SWITCH_RPC_TIMEOUT_MS = 190_000;
+const MAX_RPC_BYTES = 64 * 1024;
+const MAX_RPC_RESULT_BYTES = 1024 * 1024;
+const MAX_PENDING_RPCS = 50;
+const RPC_METHOD_RE = /^[a-z][a-zA-Z]{0,39}$/;
+// Same as extension/shared/profiles.js's PROFILE_ID_RE.
+const PROFILE_ID_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+// A switch waits for the reply already running, so it may take a while.
+const SWITCH_STATUS = { unknown: 404, locked: 409, unavailable: 409 };
+
+// Everything in C0 except tab and newline, plus DEL and all of C1 (which some
+// terminals honor as 8-bit CSI/OSC introducers), plus the invisible bidi and
+// zero-width formatting characters that make text read differently from what
+// it is. The line and paragraph separators become a newline. The zero-width
+// joiner and non-joiner stay (emoji sequences and several scripts need them).
+// Same rule as extension/shared/sanitize.js, which explains each range.
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u061c\u200b\u200e\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
+const LINE_SEPARATORS_RE = /[\u2028\u2029]/g;
+
+function stripControlChars(text) {
+  return text.replace(LINE_SEPARATORS_RE, "\n").replace(CONTROL_CHARS_RE, "");
+}
+
+// Returns null when the request plausibly comes from the local companion
+// process, or a reason string for the 403. Shared by every companion-only
+// route; add new ones to COMPANION_ONLY_ROUTES rather than re-deriving this.
+function companionOnlyRejection(req) {
+  if (req.headers.origin !== undefined) return "this route is for the companion only";
+  const site = req.headers["sec-fetch-site"];
+  if (site !== undefined && site !== "none") return "this route is for the companion only";
+  if (req.headers[COMPANION_HEADER] !== "1") return `this route is for the companion only (missing ${COMPANION_HEADER})`;
+  return null;
+}
+
+const COMPANION_ONLY_ROUTES = new Set([
+  "POST /panel/publish",
+  "GET /panel/inbox",
+  "POST /panel/drop-problem",
+  "POST /panel/trim-captures",
+  "POST /panel/activity",
+  "POST /panel/rpc-result",
+]);
+
+const EVENT_TYPES = new Set(["user", "capture", "turn-start", "chunk", "turn-end", "notice"]);
+
+function isShortString(value, max) {
+  return typeof value === "string" && value.length <= max;
+}
+
+// Copies only the fields the panel knows how to render, so a malformed or
+// oversized publish can never smuggle arbitrary data into the buffer.
+function sanitizeEvent(raw) {
+  if (!raw || typeof raw !== "object" || !EVENT_TYPES.has(raw.type)) return null;
+  const event = { type: raw.type };
+  if (raw.problemSlug !== undefined && raw.problemSlug !== null) {
+    if (!isShortString(raw.problemSlug, 200)) return null;
+    event.problemSlug = raw.problemSlug;
+  } else {
+    event.problemSlug = null;
+  }
+  if (raw.turnId !== undefined) {
+    if (!isShortString(raw.turnId, 64)) return null;
+    event.turnId = raw.turnId;
+  }
+  if (raw.text !== undefined) {
+    if (!isShortString(raw.text, MAX_TEXT_CHARS)) return null;
+    event.text = raw.text;
+  }
+  if (raw.error !== undefined) {
+    if (!isShortString(raw.error, 2000)) return null;
+    event.error = raw.error;
+  }
+  if (raw.trigger !== undefined) {
+    if (raw.trigger !== "run" && raw.trigger !== "submit") return null;
+    event.trigger = raw.trigger;
+  }
+  if (raw.problemTitle !== undefined && raw.problemTitle !== null) {
+    if (!isShortString(raw.problemTitle, 300)) return null;
+    event.problemTitle = raw.problemTitle;
+  }
+  if (raw.attemptSeq !== undefined && raw.attemptSeq !== null) {
+    if (!Number.isInteger(raw.attemptSeq) || raw.attemptSeq < 0) return null;
+    event.attemptSeq = raw.attemptSeq;
+  }
+  // The notice of a reset on a problem switch (the panel treats it as the
+  // start of a fresh session).
+  if (raw.type === "notice" && raw.switch === true) event.switch = true;
+  return event;
+}
+
+// The non-secret summary of the tutor's provider, as settings.js's
+// statusSummary makes it. Anything else is dropped.
+function sanitizeConfig(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  if (typeof raw.provider !== "string" || !/^[a-z]{1,40}$/.test(raw.provider)) return null;
+  if (!isShortString(raw.label, 100)) return null;
+  const config = { type: "config", provider: raw.provider, label: stripControlChars(raw.label) };
+  if (raw.model === null || raw.model === undefined) config.model = null;
+  else if (isShortString(raw.model, 200)) config.model = stripControlChars(raw.model);
+  else return null;
+  // The saved profile in use (an id only), left out when none is.
+  if (typeof raw.profile === "string" && PROFILE_ID_RE.test(raw.profile)) config.profile = raw.profile;
+  else if (raw.profile !== null && raw.profile !== undefined) return null;
+  return config;
+}
+
+// The live editor code a panel message may carry (read by the extension at
+// send time), reduced to the fields the companion uses. Anything malformed
+// is dropped and the message goes without it: the companion then falls back
+// to the newest recorded Run or Submit. The code itself is passed on as is;
+// the companion never prints it.
+function sanitizeSnapshot(raw) {
+  if (!raw || typeof raw !== "object" || !isShortString(raw.code, MAX_SNAPSHOT_CODE_CHARS)) return null;
+  const snapshot = { code: raw.code };
+  if (isShortString(raw.language, 50)) snapshot.language = stripControlChars(raw.language);
+  if (isShortString(raw.problemTitle, 300)) snapshot.problemTitle = stripControlChars(raw.problemTitle);
+  if (isShortString(raw.problemDescription, MAX_SNAPSHOT_DESCRIPTION_CHARS)) {
+    snapshot.problemDescription = stripControlChars(raw.problemDescription);
+  }
+  return snapshot;
+}
+
+// Whether two paths name the same file: the companion tails the file it was
+// configured with, and a trim must never cut a different one (with only
+// LEETCODE_CAPTURES_FILE or only CAPTURE_LOG_PATH set, they differ).
+function sameFile(a, b) {
+  const real = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return real(a) === real(b);
+}
+
+// captureLog, when given, is { path, trim(before) } from server.js; without
+// it the trim route answers 404.
+function createPanelBroker({ port, captureLog = null, rpcTimeoutMs = RPC_TIMEOUT_MS, switchTimeoutMs = SWITCH_RPC_TIMEOUT_MS }) {
+  const allowedHosts = new Set([`localhost:${port}`, `127.0.0.1:${port}`]);
+
+  // Identifies this run of the relay; see the file header.
+  const epoch = crypto.randomBytes(8).toString("hex");
+  let nextSeq = 1;
+  let events = []; // bounded, oldest first
+  const panelClients = new Set(); // SSE responses for panels
+  const consumers = new Set(); // SSE responses for companions (inbox)
+  let nextMessageId = 1;
+  // Replies that have started but not ended, with the text streamed so far:
+  // turnId -> { problemSlug, text, closed }. The companion ends every turn it
+  // finishes, but a companion that exits mid-reply (Ctrl+C, a crash, the
+  // terminal closed) never sends that end, and the panel would show the
+  // reply as still typing forever, in every tab opened later too. When the
+  // last companion's inbox stream goes away (and after any publish that
+  // arrives while none is connected), closeOpenTurns ends each of them as
+  // interrupted. `closed` marks one ended that way, so a companion that only
+  // lost its stream and keeps streaming the same turn reopens it.
+  const openTurns = new Map();
+  // Whether the companion is working on a turn or has one queued (it says so
+  // on POST /panel/activity). Shown in the panel's header as "Processing";
+  // cleared when the last companion goes away, since nothing will clear it
+  // then.
+  let companionBusy = false;
+  // The newest config event from the companion (see the file header).
+  let latestConfig = null;
+  // Settings calls waiting for the companion's answer: id -> { req, res, timer }.
+  const pendingRpcs = new Map();
+
+  function corsHeaders(req) {
+    // Only ever echoed for the one allowed origin; a request with no Origin
+    // header (the companion) needs no CORS headers at all.
+    if (req.headers.origin !== PANEL_ORIGIN) return {};
+    return {
+      "Access-Control-Allow-Origin": PANEL_ORIGIN,
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Last-Event-ID",
+      // Chrome's Private Network Access preflight asks for this when a public
+      // https page talks to a loopback address.
+      "Access-Control-Allow-Private-Network": "true",
+      "Access-Control-Max-Age": "600",
+      Vary: "Origin",
+    };
+  }
+
+  // The options page's fetch: Chrome and Firefox skip CORS for an extension
+  // page with host permission for the relay, but answering the preflight and
+  // echoing the origin keeps it working either way.
+  function settingsCorsHeaders(req) {
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || !EXTENSION_ORIGIN_RE.test(origin)) return {};
+    return {
+      "Access-Control-Allow-Origin": origin,
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type",
+      "Access-Control-Max-Age": "600",
+      Vary: "Origin",
+    };
+  }
+
+  function sendJson(req, res, status, body) {
+    if (res.headersSent || res.writableEnded) return;
+    const cors = req.url.startsWith("/settings/") ? settingsCorsHeaders(req) : corsHeaders(req);
+    res.writeHead(status, { "Content-Type": "application/json", ...cors });
+    res.end(JSON.stringify(body));
+  }
+
+  function sseWrite(res, { id, data }) {
+    if (id !== undefined) res.write(`id: ${id}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+  }
+
+  // openTurns lists the replies this relay has seen start and not yet end
+  // (or ended as interrupted). A panel that lost its stream marks every
+  // reply it was showing as interrupted, since a relay that died with its
+  // companion never sends their end; after a reconnect to the same run, the
+  // ones listed here are alive after all.
+  function statusEvent() {
+    const open = [];
+    for (const [turnId, turn] of openTurns) if (!turn.closed) open.push(turnId);
+    return { type: "status", companionOnline: consumers.size > 0, busy: consumers.size > 0 && companionBusy, epoch, openTurns: open };
+  }
+
+  function broadcastStatus() {
+    for (const res of panelClients) sseWrite(res, { data: statusEvent() });
+  }
+
+  function trackTurn(event) {
+    if (!event.turnId) return;
+    if (event.type === "turn-start") {
+      openTurns.delete(event.turnId);
+      openTurns.set(event.turnId, { problemSlug: event.problemSlug, text: "", closed: false });
+      // A companion that never ends its turns must not grow this forever.
+      if (openTurns.size > MAX_OPEN_TURNS) openTurns.delete(openTurns.keys().next().value);
+    } else if (event.type === "chunk") {
+      const turn = openTurns.get(event.turnId);
+      if (!turn) return;
+      turn.closed = false;
+      if (event.text && turn.text.length < MAX_TEXT_CHARS) turn.text = (turn.text + event.text).slice(0, MAX_TEXT_CHARS);
+    } else if (event.type === "turn-end") {
+      openTurns.delete(event.turnId);
+    }
+  }
+
+  // Ends every reply still streaming as interrupted, with the text it got
+  // so far (a turn-end replaces its chunks in the buffer, see addEvent). The
+  // panel shows the same "did not finish" note it uses for a relay restart.
+  function closeOpenTurns() {
+    for (const [turnId, turn] of openTurns) {
+      if (turn.closed) continue;
+      turn.closed = true;
+      const stored = { type: "turn-end", turnId, problemSlug: turn.problemSlug, text: turn.text, interrupted: true };
+      addEvent(stored, { track: false });
+    }
+  }
+
+  function addEvent(event, { track = true } = {}) {
+    if (track) trackTurn(event);
+    const stored = { ...event, seq: nextSeq++, epoch };
+    // A turn-end carries the turn's full authoritative text, so the chunks
+    // that led up to it are dead weight for anyone replaying the buffer.
+    if (stored.type === "turn-end" && stored.turnId) {
+      events = events.filter((e) => !(e.type === "chunk" && e.turnId === stored.turnId));
+    }
+    events.push(stored);
+    if (events.length > MAX_BUFFERED_EVENTS) events = events.slice(events.length - MAX_BUFFERED_EVENTS);
+    for (const res of panelClients) sseWrite(res, { id: stored.seq, data: stored });
+    return stored;
+  }
+
+  function openStream(req, res, onClose) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      // no-store, not just no-cache: a stream that never finishes would
+      // otherwise hold Chrome's HTTP-cache lock for its URL, and a second
+      // identical GET (a second leetcode tab asking for /panel/events?after=0)
+      // queues behind it forever.
+      "Cache-Control": "no-store, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+      ...corsHeaders(req),
+    });
+    res.write("retry: 2000\n\n");
+    const heartbeat = setInterval(() => res.write(": ping\n\n"), HEARTBEAT_MS);
+    heartbeat.unref();
+    req.on("close", () => {
+      clearInterval(heartbeat);
+      onClose();
+    });
+  }
+
+  // A body past maxBytes is answered with a 413, but the rest of it is still
+  // read and thrown away (up to a hard ceiling) before the connection closes:
+  // resetting the socket while the client is still uploading makes it see a
+  // network error instead of the 413 (the panel would then say the relay is
+  // unreachable rather than that the message is too long).
+  function readBody(req, res, maxBytes, onBody) {
+    let received = 0;
+    const chunks = [];
+    let aborted = false;
+    req.on("data", (chunk) => {
+      received += chunk.length;
+      if (aborted) {
+        if (received > maxBytes * 4) req.destroy();
+        return;
+      }
+      if (received > maxBytes) {
+        aborted = true;
+        chunks.length = 0;
+        res.setHeader("Connection", "close");
+        sendJson(req, res, 413, { error: "payload too large" });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      let body;
+      try {
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      } catch {
+        sendJson(req, res, 400, { error: "invalid JSON" });
+        return;
+      }
+      onBody(body);
+    });
+    req.on("error", () => {});
+  }
+
+  // Sends a settings call down the companion's inbox and answers the request
+  // with `answer(response)` -> [status, body] once the companion has, or 504
+  // after `timeoutMs`.
+  function forwardRpc(req, res, method, params, answer, timeoutMs = rpcTimeoutMs) {
+    if (consumers.size === 0) {
+      sendJson(req, res, 503, { ok: false, error: { message: "The tutor isn't running." } });
+      return;
+    }
+    if (pendingRpcs.size >= MAX_PENDING_RPCS) {
+      sendJson(req, res, 503, { ok: false, error: { message: "Too many settings calls are waiting. Try again." } });
+      return;
+    }
+    const id = crypto.randomBytes(12).toString("hex");
+    const timer = setTimeout(() => {
+      pendingRpcs.delete(id);
+      sendJson(req, res, 504, {
+        ok: false,
+        error: { message: `The tutor did not answer within ${Math.round(timeoutMs / 1000)} seconds.` },
+      });
+    }, timeoutMs);
+    timer.unref();
+    pendingRpcs.set(id, { req, res, timer, answer });
+    res.on("close", () => {
+      const pending = pendingRpcs.get(id);
+      if (pending && pending.res === res) {
+        clearTimeout(pending.timer);
+        pendingRpcs.delete(id);
+      }
+    });
+    const message = { type: "rpc", id, method, params };
+    for (const consumer of consumers) sseWrite(consumer, { data: message });
+  }
+
+  // What a panel hears back from a model switch: nothing but whether it
+  // worked, why not, and the non-secret summary of the model in use.
+  function switchAnswer(response) {
+    if (response.ok) {
+      const result = response.result || {};
+      const active = sanitizeConfig(result.active);
+      const body = { ok: true, profile: typeof result.profile === "string" && PROFILE_ID_RE.test(result.profile) ? result.profile : null };
+      if (active) body.active = { provider: active.provider, label: active.label, model: active.model };
+      return [200, body];
+    }
+    const error = response.error || {};
+    const code = typeof error.code === "string" && SWITCH_STATUS[error.code] ? error.code : "failed";
+    const message = typeof error.message === "string" ? stripControlChars(error.message).slice(0, 300) : "The switch failed.";
+    return [SWITCH_STATUS[code] || 500, { ok: false, error: { code, message } }];
+  }
+
+  // POST /settings/rpc from the extension's options page (see the file
+  // header). Returns true once handled.
+  function handleSettings(req, res, url) {
+    if (!allowedHosts.has(req.headers.host)) {
+      sendJson(req, res, 403, { error: "forbidden host" });
+      return true;
+    }
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || !EXTENSION_ORIGIN_RE.test(origin)) {
+      sendJson(req, res, 403, { error: "this route is for the extension's settings page only" });
+      return true;
+    }
+    const fetchMode = req.headers["sec-fetch-mode"];
+    if (fetchMode !== undefined && fetchMode !== "cors") {
+      sendJson(req, res, 403, { error: "only CORS requests are accepted" });
+      return true;
+    }
+    if (url.pathname !== "/settings/rpc") {
+      sendJson(req, res, 404, { error: "not found" });
+      return true;
+    }
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, settingsCorsHeaders(req));
+      res.end();
+      return true;
+    }
+    if (req.method !== "POST") {
+      sendJson(req, res, 404, { error: "not found" });
+      return true;
+    }
+    readBody(req, res, MAX_RPC_BYTES, (body) => {
+      const method = body && body.method;
+      const params = body && body.params;
+      if (typeof method !== "string" || !RPC_METHOD_RE.test(method) || (params !== undefined && (params === null || typeof params !== "object"))) {
+        sendJson(req, res, 400, { error: "a settings `method` and optional `params` object are required" });
+        return;
+      }
+      forwardRpc(req, res, method, params || {}, (response) => [200, response]);
+    });
+    return true;
+  }
+
+  // Returns true if the request was a /panel/ or /settings/ route (and has
+  // been handled), false if the caller should keep routing it.
+  function handle(req, res) {
+    const url = new URL(req.url, "http://relay.invalid");
+    if (url.pathname.startsWith("/settings/")) return handleSettings(req, res, url);
+    if (!url.pathname.startsWith("/panel/")) return false;
+
+    if (!allowedHosts.has(req.headers.host)) {
+      sendJson(req, res, 403, { error: "forbidden host" });
+      return true;
+    }
+    const origin = req.headers.origin;
+    if (origin !== undefined && origin !== PANEL_ORIGIN) {
+      sendJson(req, res, 403, { error: "forbidden origin" });
+      return true;
+    }
+
+    // Every legitimate caller makes a CORS-mode request: the panel's fetch
+    // from leetcode.com, and the companion's Node fetch (which sends
+    // Sec-Fetch-Mode: cors too). A no-cors fetch, an <img>/<script> tag or an
+    // <iframe> on some other website sends no Origin, so the check above lets
+    // it through, and although it cannot read the stream it holds one of the
+    // MAX_PANEL_STREAMS slots: twenty of them locked leetcode.com out with a
+    // 503. Refused here, before anything is counted. A browser too old to send
+    // Sec-Fetch-Mode at all is not covered; every browser the extension
+    // supports sends it.
+    const fetchMode = req.headers["sec-fetch-mode"];
+    if (fetchMode !== undefined && fetchMode !== "cors") {
+      sendJson(req, res, 403, { error: "only CORS requests are accepted" });
+      return true;
+    }
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, corsHeaders(req));
+      res.end();
+      return true;
+    }
+
+    const route = `${req.method} ${url.pathname}`;
+    if (COMPANION_ONLY_ROUTES.has(route)) {
+      const rejection = companionOnlyRejection(req);
+      if (rejection) {
+        sendJson(req, res, 403, { error: rejection });
+        return true;
+      }
+    }
+
+    if (route === "GET /panel/events") {
+      if (panelClients.size >= MAX_PANEL_STREAMS) {
+        sendJson(req, res, 503, { error: "too many open panel streams" });
+        return true;
+      }
+      const lastEventId = Number(req.headers["last-event-id"]);
+      const afterParam = Number(url.searchParams.get("after"));
+      let after = Number.isFinite(lastEventId) && lastEventId > 0 ? lastEventId : Number.isFinite(afterParam) ? afterParam : 0;
+      // A client counting from a previous run of the relay must get the whole
+      // buffer: its `after` is meaningless against this run's numbering.
+      const clientEpoch = url.searchParams.get("epoch");
+      if (clientEpoch && clientEpoch !== epoch) after = 0;
+      openStream(req, res, () => panelClients.delete(res));
+      for (const event of events) {
+        if (event.seq > after) sseWrite(res, { id: event.seq, data: event });
+      }
+      if (latestConfig) sseWrite(res, { data: latestConfig });
+      sseWrite(res, { data: statusEvent() });
+      panelClients.add(res);
+      return true;
+    }
+
+    if (route === "GET /panel/inbox") {
+      openStream(req, res, () => {
+        consumers.delete(res);
+        if (consumers.size === 0) {
+          closeOpenTurns();
+          companionBusy = false;
+        }
+        broadcastStatus();
+      });
+      consumers.add(res);
+      broadcastStatus();
+      return true;
+    }
+
+    if (route === "POST /panel/message") {
+      readBody(req, res, MAX_MESSAGE_BYTES, (body) => {
+        const text = body && typeof body.text === "string" ? stripControlChars(body.text).trim() : "";
+        const slug = body && body.problemSlug;
+        if (!text || text.length > MAX_MESSAGE_CHARS || typeof slug !== "string" || !SLUG_RE.test(slug)) {
+          sendJson(req, res, 400, { error: "text (1-8000 chars) and a valid problemSlug are required" });
+          return;
+        }
+        if (consumers.size === 0) {
+          sendJson(req, res, 503, { error: "companion offline" });
+          return;
+        }
+        const message = { id: nextMessageId++, text, problemSlug: slug };
+        const snapshot = sanitizeSnapshot(body.snapshot);
+        if (snapshot) message.snapshot = snapshot;
+        for (const consumer of consumers) sseWrite(consumer, { id: message.id, data: message });
+        sendJson(req, res, 202, { ok: true, id: message.id });
+      });
+      return true;
+    }
+
+    // The model switcher (see the file header): only an id goes on.
+    if (route === "POST /panel/switch-profile") {
+      readBody(req, res, 4096, (body) => {
+        const id = body && body.id;
+        if (typeof id !== "string" || !PROFILE_ID_RE.test(id)) {
+          sendJson(req, res, 400, { ok: false, error: { code: "invalid", message: "a saved model's `id` is required" } });
+          return;
+        }
+        forwardRpc(req, res, "switchProfile", { id }, switchAnswer, switchTimeoutMs);
+      });
+      return true;
+    }
+
+    // The companion moved on from a problem (its tutor context was reset), so
+    // that problem's transcript is no longer kept for panels that connect or
+    // reload later. Panels already showing it keep what they have.
+    if (route === "POST /panel/drop-problem") {
+      readBody(req, res, MAX_MESSAGE_BYTES, (body) => {
+        const slug = body && body.problemSlug;
+        if (typeof slug !== "string" || !SLUG_RE.test(slug)) {
+          sendJson(req, res, 400, { error: "a valid problemSlug is required" });
+          return;
+        }
+        const before = events.length;
+        // Chunks carry no slug of their own, only their turn's id.
+        const turnIds = new Set(events.filter((e) => e.problemSlug === slug && e.turnId).map((e) => e.turnId));
+        events = events.filter((e) => e.problemSlug !== slug && !(e.turnId && turnIds.has(e.turnId)));
+        for (const [turnId, turn] of openTurns) if (turn.problemSlug === slug) openTurns.delete(turnId);
+        sendJson(req, res, 200, { ok: true, dropped: before - events.length });
+      });
+      return true;
+    }
+
+    // The companion has read and handled the capture log up to `before` and
+    // asks for that prefix to go (see server.js, trimCaptureLog). It moves
+    // its own read offset back by `removed` only once this answers 200.
+    if (route === "POST /panel/trim-captures") {
+      if (!captureLog) {
+        sendJson(req, res, 404, { error: "not found" });
+        return true;
+      }
+      readBody(req, res, 4096, (body) => {
+        const before = body && body.before;
+        if (!Number.isSafeInteger(before) || before < 0 || typeof body.path !== "string" || !body.path) {
+          sendJson(req, res, 400, { error: "a byte offset `before` and the log's `path` are required" });
+          return;
+        }
+        if (!sameFile(body.path, captureLog.path)) {
+          sendJson(req, res, 409, { error: "this relay writes a different capture log" });
+          return;
+        }
+        let result;
+        try {
+          result = captureLog.trim(before);
+        } catch (err) {
+          sendJson(req, res, 500, { error: `could not trim the capture log: ${err.message}` });
+          return;
+        }
+        if (result.error) {
+          sendJson(req, res, 409, { error: result.error });
+          return;
+        }
+        sendJson(req, res, 200, { ok: true, removed: result.removed, size: result.size });
+      });
+      return true;
+    }
+
+    if (route === "POST /panel/activity") {
+      readBody(req, res, 4096, (body) => {
+        if (!body || typeof body.busy !== "boolean") {
+          sendJson(req, res, 400, { error: "a boolean `busy` is required" });
+          return;
+        }
+        if (companionBusy !== body.busy) {
+          companionBusy = body.busy;
+          broadcastStatus();
+        }
+        sendJson(req, res, 200, { ok: true });
+      });
+      return true;
+    }
+
+    // The companion's answer to a settings call (see handleSettings). The
+    // first answer wins; a late or unknown one gets a 404.
+    if (route === "POST /panel/rpc-result") {
+      readBody(req, res, MAX_RPC_RESULT_BYTES, (body) => {
+        const id = body && body.id;
+        const response = body && body.response;
+        if (typeof id !== "string" || !response || typeof response !== "object" || typeof response.ok !== "boolean") {
+          sendJson(req, res, 400, { error: "an `id` and a `response` with a boolean `ok` are required" });
+          return;
+        }
+        const pending = pendingRpcs.get(id);
+        if (!pending) {
+          sendJson(req, res, 404, { error: "no settings call is waiting for that id" });
+          return;
+        }
+        pendingRpcs.delete(id);
+        clearTimeout(pending.timer);
+        const [status, answer] = pending.answer(response);
+        sendJson(pending.req, pending.res, status, answer);
+        sendJson(req, res, 200, { ok: true });
+      });
+      return true;
+    }
+
+    if (route === "POST /panel/publish") {
+      readBody(req, res, MAX_PUBLISH_BYTES, (body) => {
+        const rawEvents = body && Array.isArray(body.events) ? body.events : [body];
+        const clean = rawEvents.map((raw) => (raw && raw.type === "config" ? sanitizeConfig(raw) : sanitizeEvent(raw)));
+        if (clean.length === 0 || clean.some((e) => e === null)) {
+          sendJson(req, res, 400, { error: "invalid event" });
+          return;
+        }
+        // A config event replaces the previous one and goes straight to every
+        // panel; it is not part of the conversation buffer.
+        const stored = [];
+        for (const event of clean) {
+          if (event.type === "config") {
+            latestConfig = { ...event, epoch };
+            for (const client of panelClients) sseWrite(client, { data: latestConfig });
+          } else {
+            stored.push(addEvent(event));
+          }
+        }
+        // A publish can land after the companion's inbox stream closed: a
+        // companion that exits sends its last batch and drops its stream at
+        // the same moment, in either order. With no companion connected
+        // nothing will end what this batch started or continued, so it is
+        // closed again right away.
+        if (consumers.size === 0) closeOpenTurns();
+        sendJson(req, res, 200, { ok: true, lastSeq: stored.length ? stored[stored.length - 1].seq : nextSeq - 1 });
+      });
+      return true;
+    }
+
+    sendJson(req, res, 404, { error: "not found" });
+    return true;
+  }
+
+  // How many panels are following the event stream right now (the relay's
+  // idle exit counts an open stream as activity).
+  return { handle, openPanelStreams: () => panelClients.size };
+}
+
+module.exports = {
+  createPanelBroker,
+  RPC_TIMEOUT_MS,
+  SWITCH_RPC_TIMEOUT_MS,
+  sanitizeEvent,
+  sanitizeConfig,
+  stripControlChars,
+  companionOnlyRejection,
+  EXTENSION_ORIGIN_RE,
+  PANEL_ORIGIN,
+  COMPANION_HEADER,
+};