@frebreco/canvas 0.3.0 → 0.4.0-next.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.3.0",
+  "version": "0.4.0-next.2",
   "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -3,71 +3,131 @@
  * canvas — a multiplayer canvas for coding agents that run on your machine.
  *
  *   canvas serve [--dir .] [--port 4418] [--web-url URL] [--tls-host NAME]
+ *                [--relay URL] [--relay-key NAME:SECRET] [--relay-via transport|signal]
+ *   canvas relay [--port 4419] [--host 0.0.0.0] [--cert FILE --key FILE]
  *
- * Starts the local server and prints the link that opens the board as its
- * host. `--tls-host` serves wss:// on that name (with `.certs/dev.{crt,key}`)
- * so a browser on another device can be the host; without it
- * the server only listens on loopback.
+ * `serve` starts the local server and prints the link that opens the board as
+ * its host. `--tls-host` serves wss:// on that name (with `.certs/dev.{crt,key}`)
+ * so a browser on another device can be the host; without it the server only
+ * listens on loopback. `--relay` puts the board on a `canvas relay` (ADR 0008)
+ * with the issuer key its operator gave you, for everything or only for
+ * peers to meet (`--relay-via signal`). Each relay flag has an environment
+ * variable: `CANVAS_RELAY`, `CANVAS_RELAY_KEY`, `CANVAS_RELAY_VIA`.
+ *
+ * `relay` runs a relay for boards on networks where peers can't connect
+ * directly; its settings are in `server/relay-config.ts`.
  */
 
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { serve } from "./server/server";
-import { defaultWebUrl } from "./server/web-url";
 
-const manifest = (await Bun.file(join(import.meta.dir, "../package.json")).json()) as {
-  version?: string;
-};
+const USAGE = `usage: canvas serve [--dir .] [--port 4418] [--web-url URL] [--tls-host NAME]
+                    [--relay URL] [--relay-key NAME:SECRET] [--relay-via transport|signal]
+       canvas relay [--port 4419] [--host 0.0.0.0] [--cert FILE --key FILE]`;
+
+const [command, ...args] = process.argv.slice(2);
+if (command === "relay") {
+  // Only what the relay needs: no agents, no terminals.
+  const { runRelay } = await import("./server/relay-cli");
+  runRelay(args, process.env);
+} else if (command === "serve") {
+  await serveBoard(args);
+} else {
+  console.log(USAGE);
+  process.exit(command === undefined ? 0 : 1);
+}
 
-const { positionals, values } = parseArgs({
-  allowPositionals: true,
-  options: {
-    dir: { type: "string", default: "." },
-    port: { type: "string", default: "4418" },
-    "web-url": {
-      type: "string",
-      default: process.env.CANVAS_WEB_URL ?? defaultWebUrl(manifest.version),
+async function serveBoard(args: string[]) {
+  const { serve } = await import("./server/server");
+  const { defaultWebUrl } = await import("./server/web-url");
+  const { parseIssuer } = await import("./server/relay-token");
+  const manifest = (await Bun.file(join(import.meta.dir, "../package.json")).json()) as {
+    version?: string;
+  };
+  const env = process.env;
+  const { values } = parseArgs({
+    args,
+    options: {
+      dir: { type: "string", default: "." },
+      port: { type: "string", default: "4418" },
+      "web-url": { type: "string", default: env.CANVAS_WEB_URL ?? defaultWebUrl(manifest.version) },
+      "tls-host": { type: "string" },
+      cert: { type: "string", default: join(import.meta.dir, "../.certs/dev.crt") },
+      key: { type: "string", default: join(import.meta.dir, "../.certs/dev.key") },
+      relay: { type: "string", default: env.CANVAS_RELAY },
+      "relay-key": { type: "string", default: env.CANVAS_RELAY_KEY },
+      "relay-via": { type: "string", default: env.CANVAS_RELAY_VIA ?? "transport" },
     },
-    "tls-host": { type: "string" },
-    cert: { type: "string", default: join(import.meta.dir, "../.certs/dev.crt") },
-    key: { type: "string", default: join(import.meta.dir, "../.certs/dev.key") },
-  },
-});
+  });
+  const fail = (message: string) => {
+    console.error(message);
+    process.exit(1);
+  };
 
-if (positionals[0] !== "serve") {
-  console.log("usage: canvas serve [--dir .] [--port 4418] [--web-url URL] [--tls-host NAME]");
-  process.exit(positionals.length === 0 ? 0 : 1);
-}
+  const dir = resolve(values.dir);
+  const tlsHost = values["tls-host"];
+  if (tlsHost && !(existsSync(values.cert) && existsSync(values.key)))
+    fail(
+      `--tls-host needs a certificate: tailscale cert --cert-file ${values.cert} --key-file ${values.key} ${tlsHost}`,
+    );
 
-const dir = resolve(values.dir);
-const tlsHost = values["tls-host"];
-if (tlsHost && !(existsSync(values.cert) && existsSync(values.key))) {
-  console.error(
-    `--tls-host needs a certificate: tailscale cert --cert-file ${values.cert} --key-file ${values.key} ${tlsHost}`,
-  );
-  process.exit(1);
-}
+  let relay = null;
+  if (values.relay) {
+    const via = values["relay-via"];
+    if (via !== "transport" && via !== "signal") fail("--relay-via is transport or signal");
+    if (!/^wss?:\/\//.test(values.relay)) fail("--relay is the relay's ws:// or wss:// URL");
+    // The web app is https: browsers only allow ws:// to their own machine.
+    if (
+      /^ws:\/\//.test(values.relay) &&
+      !/^ws:\/\/(localhost|127\.0\.0\.1|\[::1\])[:/]/.test(values.relay)
+    )
+      console.warn(
+        "  warning: browsers on the https web app only reach a relay over wss:// (ws:// only on their own machine)",
+      );
+    if (!values["relay-key"])
+      fail(
+        "--relay needs --relay-key NAME:SECRET (or CANVAS_RELAY_KEY), from the relay's operator",
+      );
+    let issuer;
+    try {
+      issuer = parseIssuer(values["relay-key"]!);
+    } catch (error) {
+      fail(`--relay-key: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    relay = {
+      url: values.relay.replace(/\/$/, ""),
+      via: via as "transport" | "signal",
+      issuer: issuer!,
+    };
+  }
 
-const { server, room } = await serve({
-  dir,
-  port: Number(values.port),
-  hostname: tlsHost ? "0.0.0.0" : "127.0.0.1",
-  ...(tlsHost && { tls: { cert: values.cert, key: values.key } }),
-  ...(manifest.version && { version: manifest.version }),
-});
+  const { server, room } = await serve({
+    dir,
+    port: Number(values.port),
+    hostname: tlsHost ? "0.0.0.0" : "127.0.0.1",
+    ...(tlsHost && { tls: { cert: values.cert, key: values.key } }),
+    ...(manifest.version && { version: manifest.version }),
+    ...(relay && { relay }),
+  });
 
-const serverUrl = tlsHost ? `wss://${tlsHost}:${server.port}` : `ws://127.0.0.1:${server.port}`;
-// Secrets ride in the fragment, which browsers never send to the web host.
-const fragment = new URLSearchParams({
-  k: room.key,
-  pk: room.hostPublicKey,
-  server: serverUrl,
-  token: room.token,
-});
-const link = `${values["web-url"].replace(/\/$/, "")}/?room=${room.roomId}#${fragment}`;
+  const serverUrl = tlsHost ? `wss://${tlsHost}:${server.port}` : `ws://127.0.0.1:${server.port}`;
+  // Secrets ride in the fragment, which browsers never send to the web host.
+  // The relay isn't named here: the host tab gets it from `canvas serve`.
+  const fragment = new URLSearchParams({
+    k: room.key,
+    pk: room.hostPublicKey,
+    server: serverUrl,
+    token: room.token,
+  });
+  const link = `${values["web-url"].replace(/\/$/, "")}/?room=${room.roomId}#${fragment}`;
 
-console.log(`canvas serving ${dir}`);
-console.log(`\n  open the board as host:\n  ${link}\n`);
-console.log("  keep this link to yourself — it controls agents on this machine.");
-console.log("  share the guest link from the board instead.\n");
+  console.log(`canvas serving ${dir}`);
+  console.log(`\n  open the board as host:\n  ${link}\n`);
+  console.log("  keep this link to yourself — it controls agents on this machine.");
+  console.log("  share the guest link from the board instead.\n");
+  if (relay)
+    console.log(
+      `  peers ${relay.via === "transport" ? "connect" : "meet"} through ${relay.url} (${relay.via}).\n`,
+    );
+}

package/src/server/relay-cli.ts

@@ -0,0 +1,51 @@
+/**
+ * `canvas relay` (ADR 0008): its flags and environment (`relay-config.ts`),
+ * then the server. Also the entry of the Docker image (`relay-main.ts`), so it
+ * pulls in nothing `canvas serve` needs.
+ */
+
+import { parseArgs } from "node:util";
+
+import { startRelay } from "./relay";
+import { relayConfig } from "./relay-config";
+
+export const RELAY_USAGE =
+  "canvas relay [--port 4419] [--host 0.0.0.0] [--cert FILE --key FILE]   (CANVAS_RELAY_KEYS=name:secret,…)";
+
+export function runRelay(args: string[], env: Readonly<Record<string, string | undefined>>) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      port: { type: "string" },
+      host: { type: "string" },
+      cert: { type: "string" },
+      key: { type: "string" },
+    },
+  });
+  let config;
+  try {
+    config = relayConfig(env, values);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(`usage: ${RELAY_USAGE}`);
+    process.exit(1);
+  }
+  const server = startRelay({ ...config, log: (line) => console.log(line) });
+  const scheme = config.tls ? "wss" : "ws";
+  console.log(
+    `canvas relay on ${scheme}://${config.hostname}:${server.port} for ${[...config.issuers.keys()].join(", ")}`,
+  );
+  const { limits } = config;
+  console.log(
+    `  limits: ${limits.peersPerRoom} peers a room, ${limits.connectionsPerIssuer} connections an issuer, ` +
+      `${limits.maxMessage / 1024 / 1024} MB a message, ${limits.messagesPerSecond} messages and ` +
+      `${limits.bytesPerSecond / 1024 / 1024} MB a second a connection`,
+  );
+  if (!config.tls) console.log("  no TLS here: put it behind a proxy that serves wss://");
+  // Containers stop with SIGTERM: close the connections, peers reconnect elsewhere or later.
+  for (const signal of ["SIGTERM", "SIGINT"] as const)
+    process.on(signal, () => {
+      void server.stop(true).then(() => process.exit(0));
+    });
+  return server;
+}

package/src/server/relay-config.ts

@@ -0,0 +1,88 @@
+/**
+ * `canvas relay`'s settings (ADR 0008): environment variables, which a flag
+ * overrides where there is one. Issuer keys only come from the environment:
+ * flags show in process lists.
+ *
+ *   CANVAS_RELAY_KEYS             name:secret[,name:secret]   required
+ *   CANVAS_RELAY_PORT   --port    4419
+ *   CANVAS_RELAY_HOST   --host    0.0.0.0
+ *   CANVAS_RELAY_TLS_CERT --cert  serve wss:// itself (else put it behind a TLS proxy)
+ *   CANVAS_RELAY_TLS_KEY  --key
+ *   CANVAS_RELAY_MAX_PEERS        64     peers in one room
+ *   CANVAS_RELAY_MAX_CONNECTIONS  256    open connections per issuer
+ *   CANVAS_RELAY_MAX_MESSAGE_MB   64     one message (a whole agent thread goes in one)
+ *   CANVAS_RELAY_RATE             500    messages per second per connection
+ *   CANVAS_RELAY_BANDWIDTH_MB     20     MB per second per connection
+ */
+
+import { parseIssuers } from "./relay-token";
+
+export interface RelayConfig {
+  readonly port: number;
+  readonly hostname: string;
+  readonly issuers: ReadonlyMap<string, string>;
+  readonly tls?: { readonly cert: string; readonly key: string };
+  readonly limits: RelayLimits;
+}
+
+export interface RelayLimits {
+  readonly peersPerRoom: number;
+  readonly connectionsPerIssuer: number;
+  /** Bytes. */
+  readonly maxMessage: number;
+  /** Messages per second, per connection; bursts up to 4 s worth. */
+  readonly messagesPerSecond: number;
+  /** Bytes per second, per connection; bursts up to 4 s worth. */
+  readonly bytesPerSecond: number;
+}
+
+export const DEFAULT_LIMITS: RelayLimits = {
+  peersPerRoom: 64,
+  connectionsPerIssuer: 256,
+  maxMessage: 64 * 1024 * 1024,
+  messagesPerSecond: 500,
+  bytesPerSecond: 20 * 1024 * 1024,
+};
+
+export interface RelayFlags {
+  readonly port?: string;
+  readonly host?: string;
+  readonly cert?: string;
+  readonly key?: string;
+}
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+export function relayConfig(env: Env, flags: RelayFlags = {}): RelayConfig {
+  const issuers = parseIssuers(env.CANVAS_RELAY_KEYS ?? "");
+  if (issuers.size === 0)
+    throw new Error("canvas relay needs issuer keys: CANVAS_RELAY_KEYS=name:secret[,name:secret]");
+  const cert = flags.cert ?? env.CANVAS_RELAY_TLS_CERT;
+  const key = flags.key ?? env.CANVAS_RELAY_TLS_KEY;
+  if (Boolean(cert) !== Boolean(key))
+    throw new Error("TLS needs both a certificate and its key (CANVAS_RELAY_TLS_CERT and _KEY)");
+  const number = (name: string, fallback: number, scale = 1) => {
+    const text = env[name];
+    if (text === undefined || text === "") return Math.round(fallback * scale);
+    const value = Number(text);
+    if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a positive number`);
+    return Math.round(value * scale);
+  };
+  const MB = 1024 * 1024;
+  return {
+    port: Number(flags.port ?? env.CANVAS_RELAY_PORT ?? 4419),
+    hostname: flags.host ?? env.CANVAS_RELAY_HOST ?? "0.0.0.0",
+    issuers,
+    ...(cert && key && { tls: { cert, key } }),
+    limits: {
+      peersPerRoom: number("CANVAS_RELAY_MAX_PEERS", DEFAULT_LIMITS.peersPerRoom),
+      connectionsPerIssuer: number(
+        "CANVAS_RELAY_MAX_CONNECTIONS",
+        DEFAULT_LIMITS.connectionsPerIssuer,
+      ),
+      maxMessage: number("CANVAS_RELAY_MAX_MESSAGE_MB", DEFAULT_LIMITS.maxMessage / MB, MB),
+      messagesPerSecond: number("CANVAS_RELAY_RATE", DEFAULT_LIMITS.messagesPerSecond),
+      bytesPerSecond: number("CANVAS_RELAY_BANDWIDTH_MB", DEFAULT_LIMITS.bytesPerSecond / MB, MB),
+    },
+  };
+}

package/src/server/relay-main.ts

@@ -0,0 +1,4 @@
+// The Docker image's entry (`Dockerfile`): `canvas relay` alone, bundled into one file.
+import { runRelay } from "./relay-cli";
+
+runRelay(process.argv.slice(2), process.env);

package/src/server/relay-token.ts

@@ -0,0 +1,106 @@
+/**
+ * Who may use a `canvas relay` (ADR 0008). The relay's operator gives each
+ * host (or team) an issuer key; `canvas serve` signs tokens with it, one for
+ * the host and one for guest links, each good for one relay room
+ * (`shared/relay-room.ts`) and 30 days. The relay checks them statelessly: the
+ * issuer is still configured, the HMAC matches, the room is the one joined,
+ * the token hasn't expired. Removing an issuer revokes all it signed.
+ *
+ *   v1.<issuer>.<room>.<h|g>.<expires, unix seconds>.<HMAC-SHA256, base64url>
+ *
+ * Only `canvas serve` and the relay handle tokens; peers pass them on.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export type RelayRole = "host" | "guest";
+
+export interface RelayToken {
+  readonly issuer: string;
+  readonly room: string;
+  readonly role: RelayRole;
+  /** Unix seconds. */
+  readonly expires: number;
+}
+
+export interface Issuer {
+  readonly name: string;
+  readonly secret: string;
+}
+
+export const TOKEN_DAYS = 30;
+const VERSION = "v1";
+const ROLE = { host: "h", guest: "g" } as const;
+
+const hmac = (secret: string, text: string) =>
+  createHmac("sha256", secret).update(text).digest("base64url");
+
+export function signRelayToken(
+  issuer: Issuer,
+  room: string,
+  role: RelayRole,
+  now = Date.now(),
+): string {
+  const expires = Math.floor(now / 1000) + TOKEN_DAYS * 86_400;
+  const body = [VERSION, issuer.name, room, ROLE[role], expires].join(".");
+  return `${body}.${hmac(issuer.secret, body)}`;
+}
+
+export type TokenCheck =
+  | { readonly ok: true; readonly token: RelayToken }
+  | { readonly ok: false; readonly reason: string };
+
+/** `issuers`: issuer name → secret, as the relay is configured. */
+export function verifyRelayToken(
+  text: string,
+  issuers: ReadonlyMap<string, string>,
+  now = Date.now(),
+): TokenCheck {
+  const parts = text.split(".");
+  if (parts.length !== 6 || parts[0] !== VERSION) return { ok: false, reason: "malformed token" };
+  const [, issuer, room, role, expires, signature] = parts as [string, ...string[]];
+  const secret = issuers.get(issuer!);
+  if (secret === undefined) return { ok: false, reason: `unknown issuer ${issuer}` };
+  const expected = Buffer.from(hmac(secret, parts.slice(0, 5).join(".")));
+  const given = Buffer.from(signature!);
+  if (expected.length !== given.length || !timingSafeEqual(expected, given))
+    return { ok: false, reason: "bad signature" };
+  if (role !== "h" && role !== "g") return { ok: false, reason: "bad role" };
+  const seconds = Number(expires);
+  if (!Number.isFinite(seconds) || seconds * 1000 < now) return { ok: false, reason: "expired" };
+  return {
+    ok: true,
+    token: {
+      issuer: issuer!,
+      room: room!,
+      role: role === "h" ? "host" : "guest",
+      expires: seconds,
+    },
+  };
+}
+
+/** `name:secret,name:secret`: how issuer keys are configured (`CANVAS_RELAY_KEYS`). */
+export function parseIssuers(text: string): Map<string, string> {
+  const issuers = new Map<string, string>();
+  for (const entry of text
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)) {
+    const colon = entry.indexOf(":");
+    if (colon <= 0 || colon === entry.length - 1)
+      throw new Error(`issuer key "${entry}" is not name:secret`);
+    const name = entry.slice(0, colon);
+    if (!/^[\w-]+$/.test(name))
+      throw new Error(`issuer name "${name}" may only use letters, digits, _ and -`);
+    issuers.set(name, entry.slice(colon + 1));
+  }
+  return issuers;
+}
+
+/** One `name:secret` (`CANVAS_RELAY_KEY`): the issuer key a host signs with. */
+export function parseIssuer(text: string): Issuer {
+  const issuers = [...parseIssuers(text)];
+  if (issuers.length !== 1) throw new Error("the relay key is one name:secret");
+  const [[name, secret]] = issuers as [[string, string]];
+  return { name, secret };
+}

package/src/server/relay.ts

@@ -0,0 +1,297 @@
+/**
+ * `canvas relay` (ADR 0008): for networks where peers can't reach the public
+ * Nostr relays, or each other over WebRTC. It stores nothing and reads
+ * nothing; it forwards what peers send, to peers holding a token signed with
+ * one of its issuer keys (`relay-token.ts`).
+ *
+ *   /transport  everything, end-to-end encrypted by the peers
+ *               (`shared/relay-protocol.ts`); the token comes in the join
+ *   /signal     trystero's ws-relay protocol: peers find each other here,
+ *               then connect over WebRTC. `?t=<token>`, as the trystero
+ *               client can't send one otherwise
+ *   /health     counts, for monitoring: no rooms, no issuers
+ *
+ * One relay serves any number of boards and hosts: rooms appear on first
+ * join and go with the last peer. Limits (`relay-config.ts`) keep one board or
+ * issuer from starving the rest.
+ */
+
+import type { Server, ServerWebSocket } from "bun";
+
+import {
+  decodeFrame,
+  encodeFrame,
+  RELAY_HOST_REPLACED,
+  RELAY_RATE_LIMITED,
+  RELAY_REFUSED,
+  type RelayClientControl,
+  type RelayServerControl,
+} from "../shared/relay-protocol";
+import { DEFAULT_LIMITS, type RelayLimits } from "./relay-config";
+import { verifyRelayToken, type RelayRole } from "./relay-token";
+
+export interface RelayOptions {
+  readonly port: number;
+  readonly hostname: string;
+  /** Issuer name → secret. */
+  readonly issuers: ReadonlyMap<string, string>;
+  readonly tls?: { readonly cert: string; readonly key: string };
+  readonly limits?: Partial<RelayLimits>;
+  /** How long a `/transport` connection may take to join. */
+  readonly joinTimeoutMs?: number;
+  readonly log?: (line: string) => void;
+}
+
+type Socket = ServerWebSocket<SocketData>;
+interface Common {
+  /** Set once admitted: counts against the issuer's connections. */
+  issuer: string | null;
+  readonly budget: Budget;
+}
+type SocketData =
+  | (Common & { readonly path: "signal"; readonly claimed: string })
+  | (Common & {
+      readonly path: "transport";
+      room: string | null;
+      peer: string | null;
+      role: RelayRole | null;
+      timer: ReturnType<typeof setTimeout> | null;
+    });
+type TransportSocket = Socket & { data: { path: "transport" } };
+
+const PEER_ID = /^[\w-]{1,64}$/;
+/** Signalling carries offers, not data: small messages only. */
+const MAX_SIGNAL_MESSAGE = 64 * 1024;
+
+export function startRelay(options: RelayOptions): Server<SocketData> {
+  const { issuers, log = () => {} } = options;
+  const limits: RelayLimits = { ...DEFAULT_LIMITS, ...options.limits };
+  /** room → peer id → socket */
+  const rooms = new Map<string, Map<string, Socket>>();
+  const perIssuer = new Map<string, number>();
+
+  const control = (ws: Socket, message: RelayServerControl) => ws.send(JSON.stringify(message));
+  const refuse = (ws: Socket, message: string) => {
+    control(ws, { t: "error", message });
+    ws.close(RELAY_REFUSED, message.slice(0, 120));
+  };
+
+  /** Count a connection against its issuer, if the issuer has room for it. */
+  function admit(ws: Socket, issuer: string): boolean {
+    const open = perIssuer.get(issuer) ?? 0;
+    if (open >= limits.connectionsPerIssuer) return false;
+    perIssuer.set(issuer, open + 1);
+    ws.data.issuer = issuer;
+    return true;
+  }
+
+  function release(ws: Socket) {
+    const { issuer } = ws.data;
+    if (!issuer) return;
+    const open = (perIssuer.get(issuer) ?? 1) - 1;
+    if (open > 0) perIssuer.set(issuer, open);
+    else perIssuer.delete(issuer);
+    ws.data.issuer = null;
+  }
+
+  /** Within the connection's budget, or it's closed; the peer reconnects later. */
+  function spend(ws: Socket, bytes: number): boolean {
+    if (ws.data.budget.spend(bytes)) return true;
+    control(ws, { t: "error", message: "rate limited: too many messages or bytes" });
+    ws.close(RELAY_RATE_LIMITED, "rate limited");
+    return false;
+  }
+
+  function join(ws: TransportSocket, message: RelayClientControl) {
+    if (ws.data.room) return refuse(ws, "already joined");
+    if (typeof message.peer !== "string" || !PEER_ID.test(message.peer))
+      return refuse(ws, "bad peer id");
+    const check = verifyRelayToken(String(message.token), issuers);
+    if (!check.ok) return refuse(ws, `token refused: ${check.reason}`);
+    if (check.token.room !== message.room) return refuse(ws, "token refused: for another room");
+    const room = rooms.get(message.room) ?? new Map<string, Socket>();
+    if (room.has(message.peer)) return refuse(ws, "peer id in use");
+    if (room.size >= limits.peersPerRoom) return refuse(ws, "room full");
+    if (!admit(ws, check.token.issuer))
+      return refuse(ws, `issuer ${check.token.issuer} is at its connection limit`);
+    // One host per room: a newer host tab takes over, as with `canvas serve`.
+    if (check.token.role === "host")
+      for (const other of room.values())
+        if (other.data.path === "transport" && other.data.role === "host")
+          other.close(RELAY_HOST_REPLACED, "another host tab joined");
+
+    if (ws.data.timer) clearTimeout(ws.data.timer);
+    rooms.set(message.room, room);
+    const peers = [...room.keys()];
+    room.set(message.peer, ws);
+    Object.assign(ws.data, { room: message.room, peer: message.peer, role: check.token.role });
+    control(ws, { t: "joined", peers });
+    for (const other of room.values())
+      if (other !== ws) control(other, { t: "peer-join", peer: message.peer });
+    log(
+      `join ${check.token.issuer}/${check.token.role} (${room.size} in room, ${rooms.size} rooms)`,
+    );
+  }
+
+  function leave(ws: TransportSocket) {
+    if (ws.data.timer) clearTimeout(ws.data.timer);
+    const { room: name, peer } = ws.data;
+    if (!name || !peer) return;
+    const room = rooms.get(name);
+    if (room?.get(peer) !== ws) return;
+    room.delete(peer);
+    if (room.size === 0) rooms.delete(name);
+    else for (const other of room.values()) control(other, { t: "peer-leave", peer });
+  }
+
+  function forward(ws: TransportSocket, frame: Uint8Array) {
+    const room = ws.data.room ? rooms.get(ws.data.room) : undefined;
+    if (!room || !ws.data.peer) return;
+    const decoded = decodeFrame<{ to?: unknown }>(frame);
+    if (!decoded) return;
+    const out = encodeFrame({ from: ws.data.peer }, decoded.payload);
+    const to = decoded.header.to;
+    const targets = Array.isArray(to)
+      ? to.flatMap((id) => {
+          const target = room.get(String(id));
+          return target && target !== ws ? [target] : [];
+        })
+      : [...room.values()].filter((s) => s !== ws);
+    for (const target of targets) target.send(out);
+  }
+
+  /** trystero's ws-relay protocol, on Bun's pub/sub (finding 15). */
+  function signal(ws: Socket, raw: string | Buffer) {
+    if (raw.length > MAX_SIGNAL_MESSAGE) return;
+    let message: { type?: string; topic?: unknown; payload?: unknown };
+    try {
+      message = JSON.parse(String(raw)) as typeof message;
+    } catch {
+      return;
+    }
+    if (typeof message.topic !== "string") return;
+    const topic = `signal:${message.topic}`;
+    if (message.type === "subscribe") ws.subscribe(topic);
+    else if (message.type === "unsubscribe") ws.unsubscribe(topic);
+    else if (message.type === "publish")
+      ws.publish(topic, JSON.stringify({ topic: message.topic, payload: message.payload }));
+  }
+
+  const budget = () => new Budget(limits.messagesPerSecond, limits.bytesPerSecond);
+
+  return Bun.serve<SocketData>({
+    port: options.port,
+    hostname: options.hostname,
+    ...(options.tls && {
+      tls: { cert: Bun.file(options.tls.cert), key: Bun.file(options.tls.key) },
+    }),
+    fetch(req, server) {
+      const url = new URL(req.url);
+      if (url.pathname === "/transport") {
+        const data: SocketData = {
+          path: "transport",
+          issuer: null,
+          budget: budget(),
+          room: null,
+          peer: null,
+          role: null,
+          timer: null,
+        };
+        if (server.upgrade(req, { data })) return;
+        return new Response("a WebSocket endpoint\n", { status: 426 });
+      }
+      if (url.pathname === "/signal") {
+        const check = verifyRelayToken(url.searchParams.get("t") ?? "", issuers);
+        if (!check.ok) return new Response(`token refused: ${check.reason}\n`, { status: 401 });
+        const data: SocketData = {
+          path: "signal",
+          claimed: check.token.issuer,
+          issuer: null,
+          budget: budget(),
+        };
+        if (server.upgrade(req, { data })) return;
+        return new Response("a WebSocket endpoint\n", { status: 426 });
+      }
+      if (url.pathname === "/health") {
+        let peers = 0;
+        for (const room of rooms.values()) peers += room.size;
+        const connections = [...perIssuer.values()].reduce((sum, n) => sum + n, 0);
+        return Response.json({ ok: true, rooms: rooms.size, peers, connections });
+      }
+      if (url.pathname === "/") return new Response("canvas relay\n");
+      return new Response("not found\n", { status: 404 });
+    },
+    websocket: {
+      maxPayloadLength: limits.maxMessage,
+      open(ws) {
+        if (ws.data.path === "signal") {
+          if (!admit(ws, ws.data.claimed)) refuse(ws, "issuer at its connection limit");
+          return;
+        }
+        // A `/transport` connection counts once its join is admitted; until
+        // then it only gets a few seconds.
+        const transport = ws as TransportSocket;
+        transport.data.timer = setTimeout(() => {
+          if (!transport.data.room) refuse(transport, "no join in time");
+        }, options.joinTimeoutMs ?? 10_000);
+      },
+      message(ws, raw) {
+        if (!spend(ws, raw.length)) return;
+        if (ws.data.path === "signal") return signal(ws, raw);
+        const transport = ws as TransportSocket;
+        if (typeof raw !== "string") return forward(transport, new Uint8Array(raw));
+        let message: RelayClientControl;
+        try {
+          message = JSON.parse(raw) as RelayClientControl;
+        } catch {
+          return refuse(ws, "bad message");
+        }
+        if (message.t === "join") join(transport, message);
+      },
+      close(ws) {
+        if (ws.data.path === "transport") leave(ws as TransportSocket);
+        release(ws);
+      },
+    },
+  });
+}
+
+/** Two token buckets: messages and bytes per second, bursts up to four seconds' worth. */
+export class Budget {
+  private messages: number;
+  private bytes: number;
+  /** When it was last spent from; refilling starts at the first spend. */
+  private last: number | null = null;
+
+  constructor(
+    private readonly messagesPerSecond: number,
+    private readonly bytesPerSecond: number,
+    private readonly burstSeconds = 4,
+  ) {
+    this.messages = messagesPerSecond * burstSeconds;
+    this.bytes = bytesPerSecond * burstSeconds;
+  }
+
+  spend(bytes: number, now = performance.now()): boolean {
+    const seconds = this.last === null ? 0 : Math.max(0, now - this.last) / 1000;
+    this.last = now;
+    this.messages = Math.min(
+      this.messagesPerSecond * this.burstSeconds,
+      this.messages + seconds * this.messagesPerSecond,
+    );
+    this.bytes = Math.min(
+      this.bytesPerSecond * this.burstSeconds,
+      this.bytes + seconds * this.bytesPerSecond,
+    );
+    // One message may be larger than the burst (a whole thread): let it through
+    // on a full bucket, and go into debt for it.
+    if (
+      this.messages < 1 ||
+      (this.bytes < bytes && this.bytes < this.bytesPerSecond * this.burstSeconds)
+    )
+      return false;
+    this.messages -= 1;
+    this.bytes -= bytes;
+    return true;
+  }
+}

package/src/server/server.ts

@@ -8,13 +8,21 @@
 import type { ServerWebSocket } from "bun";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { HOST_REPLACED, type ClientToServer, type ServerToClient } from "../shared/protocol";
+import {
+  HOST_REPLACED,
+  type ClientToServer,
+  type RelayVia,
+  type ServerToClient,
+  type WelcomeRelay,
+} from "../shared/protocol";
+import { relayRoom } from "../shared/relay-room";
 import { AgentManager, detectAgents } from "./agents";
 import { BoardMcp } from "./board-mcp";
 import { Files } from "./files";
 import { Scratch } from "./scratch";
 import { canvasSkills } from "./skills";
 import { Store } from "./store";
+import { signRelayToken, type Issuer } from "./relay-token";
 import { Terminals } from "./terminals";
 
 export interface ServeOptions {
@@ -24,12 +32,33 @@ export interface ServeOptions {
   readonly tls?: { readonly cert: string; readonly key: string };
   /** The published version this runs as; none for a checkout. */
   readonly version?: string;
+  /** Guests reach the board through this `canvas relay` (ADR 0008). */
+  readonly relay?: ServeRelay;
+}
+
+export interface ServeRelay {
+  readonly url: string;
+  readonly via: RelayVia;
+  /** The issuer key the relay's operator gave this host. */
+  readonly issuer: Issuer;
 }
 
 export async function serve(options: ServeOptions) {
   const store = new Store(options.dir);
   excludeFromGit(options.dir);
   const room = await store.room();
+  const relayRoomName = options.relay ? await relayRoom(room.key) : null;
+  // Signed for every host tab that connects: its token and the one its guest
+  // links carry are good for 30 days from then.
+  const relaySetup = (): WelcomeRelay | null =>
+    options.relay && relayRoomName
+      ? {
+          url: options.relay.url,
+          via: options.relay.via,
+          hostToken: signRelayToken(options.relay.issuer, relayRoomName, "host"),
+          guestToken: signRelayToken(options.relay.issuer, relayRoomName, "guest"),
+        }
+      : null;
   // The host tab: the board, and so every board tool call, lives there.
   let host: ServerWebSocket<unknown> | null = null;
   const broadcast = (message: ServerToClient) => host?.send(JSON.stringify(message));
@@ -166,6 +195,7 @@ export async function serve(options: ServeOptions) {
             agents: agentDefinitions.map(({ kind, label }) => ({ kind, label })),
             board: board ? Buffer.from(board).toString("base64") : null,
             sessions: agents.snapshots(),
+            relay: relaySetup(),
           } satisfies ServerToClient),
         );
       },

package/src/shared/protocol.ts

@@ -157,6 +157,19 @@ export interface RoomSecrets {
   readonly hostPrivateKey: JsonWebKey;
 }
 
+/** How a board uses its `canvas relay` (ADR 0008): for everything, or only to meet. */
+export type RelayVia = "transport" | "signal";
+
+/** What the host's browser needs for the board's relay, signed fresh for each host tab. */
+export interface WelcomeRelay {
+  readonly url: string;
+  readonly via: RelayVia;
+  /** The host tab's own token. */
+  readonly hostToken: string;
+  /** The token guest links carry. */
+  readonly guestToken: string;
+}
+
 /**
  * Close code of a host browser's WebSocket when another one connected: one
  * host tab at a time, and the replaced one must not reconnect by itself, or
@@ -219,6 +232,8 @@ export type ServerToClient =
       /** base64 Yjs update of the persisted board, if any. */
       readonly board: string | null;
       readonly sessions: ReadonlyArray<SessionSnapshot>;
+      /** The board's `canvas relay`, if it uses one (ADR 0008). */
+      readonly relay?: WelcomeRelay | null;
     }
   | { readonly t: "agent-meta"; readonly meta: SessionMeta }
   | { readonly t: "agent-event"; readonly sessionId: string; readonly event: AgentEvent }

package/src/shared/relay-protocol.ts

@@ -0,0 +1,58 @@
+/**
+ * The wire of `canvas relay`'s `/transport` (ADR 0008). The relay forwards
+ * opaque bytes between the peers of a room and knows nothing else: payloads
+ * are end-to-end encrypted by the peers (`web/lib/transport/relay.ts`).
+ *
+ * Control messages are JSON text frames. Data is a binary frame:
+ *
+ *   [u32 header length][header, JSON][payload]
+ *
+ * peer → relay header: `{to?: string[]}` (absent: everyone else in the room)
+ * relay → peer header: `{from: string}`, stamped by the relay — a peer can't
+ * send as another.
+ */
+
+export type RelayClientControl = {
+  readonly t: "join";
+  readonly room: string;
+  /** Chosen by the peer; the relay binds it to this socket for as long as it's open. */
+  readonly peer: string;
+  readonly token: string;
+};
+
+export type RelayServerControl =
+  | { readonly t: "joined"; readonly peers: ReadonlyArray<string> }
+  | { readonly t: "peer-join"; readonly peer: string }
+  | { readonly t: "peer-leave"; readonly peer: string }
+  | { readonly t: "error"; readonly message: string };
+
+/** Close codes. The peer doesn't reconnect after these, as retrying can't help. */
+export const RELAY_REFUSED = 4401;
+/** A newer host tab joined the room. */
+export const RELAY_HOST_REPLACED = 4409;
+/** Over the connection's message or byte rate; the peer reconnects and joins again. */
+export const RELAY_RATE_LIMITED = 4429;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function encodeFrame(header: object, payload: Uint8Array): Uint8Array<ArrayBuffer> {
+  const head = encoder.encode(JSON.stringify(header));
+  const frame = new Uint8Array(4 + head.length + payload.length);
+  new DataView(frame.buffer).setUint32(0, head.length);
+  frame.set(head, 4);
+  frame.set(payload, 4 + head.length);
+  return frame;
+}
+
+export function decodeFrame<H>(frame: Uint8Array): { header: H; payload: Uint8Array } | null {
+  if (frame.length < 4) return null;
+  const length = new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(0);
+  if (4 + length > frame.length) return null;
+  try {
+    const header = JSON.parse(decoder.decode(frame.subarray(4, 4 + length))) as H;
+    return { header, payload: frame.subarray(4 + length) };
+  } catch {
+    return null;
+  }
+}

package/src/shared/relay-room.ts

@@ -0,0 +1,40 @@
+/**
+ * What peers of a board derive from its key for a `canvas relay` (ADR 0008):
+ * the relay room, and the key that seals messages over the relay transport.
+ *
+ * The relay room comes from the board key `k`, not its `?room=` id: the web
+ * host sees that id, and the relay shouldn't be able to match its rooms to
+ * board URLs — nor anyone guess a room without the key.
+ *
+ * WebCrypto only: `canvas serve` and the browser both use it.
+ */
+
+const encoder = new TextEncoder();
+
+export function b64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Key material from a board key: HKDF-SHA256 with a purpose label. */
+export async function deriveBits(
+  boardKey: string,
+  info: string,
+  bits = 256,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const base = await crypto.subtle.importKey("raw", encoder.encode(boardKey), "HKDF", false, [
+    "deriveBits",
+  ]);
+  const derived = await crypto.subtle.deriveBits(
+    { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: encoder.encode(info) },
+    base,
+    bits,
+  );
+  return new Uint8Array(derived);
+}
+
+/** The relay room of a board: the same for everyone holding its key, meaningless without it. */
+export async function relayRoom(boardKey: string): Promise<string> {
+  return b64url(await deriveBits(boardKey, "canvas-relay-room", 128));
+}