tickcli-js 0.0.0-stage → 0.1.1

package/src/node.ts

@@ -0,0 +1,245 @@
+// tickcli on Node: sockets (the ws package) to the hub, plus the small security pieces every host app needs. No web framework assumed:
+// use attach() with a plain ws server, or socketEvents() from any framework's WebSocket upgrade helper.
+//
+// Who someone is never comes from the game page. Two ways in, both decided by the host app:
+//   tickets  - the app signs a short, one-time ticket for a signed-in person; the page's trusted wrapper sends it as the socket's FIRST message
+//              (not in the address: proxies write addresses to their logs). Until it arrives the socket counts as unverified (capped, 5 s).
+//   passes   - for anonymous visitors: the app sets a pass cookie (HttpOnly, SameSite=Strict, scoped to one path) and checks it at the upgrade.
+// Plus: the Origin header must be present and name the site itself (sameSite()).
+import crypto from "node:crypto";
+import type { WebSocket } from "ws";
+import fs from "node:fs";
+import path from "node:path";
+import { CLOSE, type Conn, type RoomHub, type SavePort, type Session, type Who } from "./hub.ts";
+
+/** A game's version: a short hash of the page. Players on another version are told to reload. */
+/** A peer that is this machine or a private network: the only kind whose X-Forwarded-For is believed (your proxy, not the internet). */
+const PRIVATE_PEER = /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|::1$|f[cd][0-9a-f]{2}:|fe80:)/i;
+
+/**
+ * The client's address for the per-address limits. Behind a proxy (Caddy, nginx) every socket comes from the proxy, so all players would
+ * share one address and the limits (20 sockets, 30 joins a minute) would cap the whole server: with `trustProxy`, a request from a private
+ * or loopback peer is taken at the last X-Forwarded-For entry (the address the proxy saw). From any other peer the header is ignored, so a
+ * player cannot pick their own address.
+ */
+export function clientAddress(req: { socket: { remoteAddress?: string }; headers: Record<string, string | string[] | undefined> }, trustProxy = false): string {
+  const peer = String(req.socket.remoteAddress || "?").replace(/^::ffff:/i, "");
+  if (!trustProxy || !PRIVATE_PEER.test(peer)) return peer;
+  const raw = req.headers["x-forwarded-for"];
+  const list = (Array.isArray(raw) ? raw.join(",") : String(raw || "")).split(",").map((x) => x.trim()).filter(Boolean);
+  const last = (list[list.length - 1] || "").replace(/^::ffff:/i, "");
+  return /^[0-9a-f.:]{2,45}$/i.test(last) ? last : peer;
+}
+
+export const gameHash = (bytes: Uint8Array | string) => crypto.createHash("sha256").update(bytes).digest("base64url").slice(0, 16);
+
+/** Hosts from a comma list of origins or host names ("https://a.example, b.example:8443"). */
+export const parseOrigins = (v: string | undefined) => String(v || "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean).map((s) => { try { return new URL(s.includes("://") ? s : `https://${s}`).host; } catch { return s; } });
+
+/**
+ * Same-site check for a socket upgrade (and any route that hands out a pass): Origin required, its host must be the host the request came to
+ * (the scheme is not compared: behind a TLS proxy the app sees http), and with an allow list it must be on it. Sec-Fetch-Site, when sent, must say
+ * same-origin. `header` reads one request header by lower-case name.
+ */
+export function sameSite(header: (name: string) => string | undefined, allow: string[] = []): boolean {
+  const origin = header("origin");
+  if (!origin) return false;
+  const site = header("sec-fetch-site");
+  if (site && site !== "same-origin") return false;
+  let host = "";
+  try { host = new URL(origin).host.toLowerCase(); } catch { return false; }
+  const own = (header("host") || "").toLowerCase();
+  if (!host || host !== own) return false;
+  return !allow.length || allow.includes(host);
+}
+
+// The purpose labels below ("tickcli guest pass", "tickcli ticket") are part of every pass and ticket's signature: changing them signs out
+// every anonymous player and orphans the games saved under their seat. Never rename them.
+const hmacKey = (secret: string | Buffer, purpose: string) => crypto.createHmac("sha256", Buffer.from(secret)).update(purpose).digest();
+
+/** Anonymous passes: "<random>.<mac>", the mac binds the pass to one scope (a public link, a lobby page). Nothing is stored. */
+export class GuestPasses {
+  private key: Buffer;
+  constructor(secret: string | Buffer) { this.key = hmacKey(secret, "tickcli guest pass"); }
+  private mac(scope: string, r: string) { return crypto.createHmac("sha256", this.key).update(`${scope}|${r}`).digest("base64url").slice(0, 22); }
+  issue(scope: string): string { const r = crypto.randomBytes(16).toString("base64url"); return `${r}.${this.mac(scope, r)}`; }
+  /** The pass id (never the pass itself) when the value is a pass for this scope, else null. */
+  check(scope: string, value: string | undefined): string | null {
+    const m = /^([A-Za-z0-9_-]{22})\.([A-Za-z0-9_-]{22})$/.exec(String(value || ""));
+    if (!m) return null;
+    const want = Buffer.from(this.mac(scope, m[1])), got = Buffer.from(m[2]);
+    return want.length === got.length && crypto.timingSafeEqual(want, got) ? m[1] : null;
+  }
+  /** "Guest 4821": a stable default name from a pass id. */
+  static defaultName(id: string) { return `Guest ${1000 + (crypto.createHash("sha256").update(id).digest().readUInt32BE(0) % 9000)}`; }
+  /** The Set-Cookie value for a pass (HttpOnly, SameSite=Strict, limited to `path`). */
+  static cookie(name: string, pass: string, path: string, secure: boolean, maxAgeSec = 400 * 24 * 3600) {
+    return `${name}=${pass}; Max-Age=${maxAgeSec}; Path=${path}; HttpOnly; SameSite=Strict${secure ? "; Secure" : ""}`;
+  }
+}
+
+/** One-time tickets: HMAC-signed claims with an expiry and an id that can be spent once (kept in memory until it expires). */
+export class Tickets<C extends object = Record<string, unknown>> {
+  private key: Buffer;
+  private spent = new Map<string, number>();
+  readonly ttlSec: number;
+  constructor(secret: string | Buffer, ttlSec = 30) { this.key = hmacKey(secret, "tickcli ticket"); this.ttlSec = ttlSec; }
+  issue(claims: C): string {
+    const body = Buffer.from(JSON.stringify({ c: claims, exp: Date.now() + this.ttlSec * 1000, j: crypto.randomBytes(12).toString("base64url") })).toString("base64url");
+    return `${body}.${crypto.createHmac("sha256", this.key).update(body).digest("base64url")}`;
+  }
+  /** The claims of a valid, unexpired, unused ticket; taking it spends it. */
+  take(ticket: unknown): C | null {
+    if (typeof ticket !== "string" || ticket.length > 4000) return null;
+    const [body, mac] = ticket.split(".");
+    if (!body || !mac) return null;
+    const want = crypto.createHmac("sha256", this.key).update(body).digest(), got = Buffer.from(mac, "base64url");
+    if (got.length !== want.length || !crypto.timingSafeEqual(got, want)) return null;
+    let t: { c: C; exp: number; j: string };
+    try { t = JSON.parse(Buffer.from(body, "base64url").toString()); } catch { return null; }
+    const now = Date.now();
+    if (!t || typeof t.exp !== "number" || t.exp < now || typeof t.j !== "string") return null;
+    if (this.spent.size > 10_000) for (const [k, exp] of this.spent) if (exp < now) this.spent.delete(k);
+    if (this.spent.has(t.j)) return null;
+    this.spent.set(t.j, t.exp + 1000);
+    return t.c;
+  }
+}
+
+/** The hub's view of one ws socket. */
+export const connOf = (ws: WebSocket): Conn => ({
+  send: (d: string) => { if (ws.readyState === 1) ws.send(d); },
+  close: (code: number, reason: string) => { try { ws.close(code, reason.slice(0, 120)); } catch { ws.terminate(); } },
+  buffered: () => ws.bufferedAmount,
+});
+
+/** Pings every socket every 30 s; one that did not answer the last ping is cut (a phone that went away without closing). */
+export class Heartbeat {
+  private live = new Map<WebSocket, boolean>();
+  private timer: ReturnType<typeof setInterval>;
+  constructor(ms = 30_000) {
+    this.timer = setInterval(() => {
+      for (const [ws, ok] of this.live) {
+        if (!ok) { ws.terminate(); this.live.delete(ws); continue; }
+        this.live.set(ws, false);
+        try { ws.ping(); } catch { /* closing */ }
+      }
+    }, ms);
+    this.timer.unref?.();
+  }
+  add(ws: WebSocket) { this.live.set(ws, true); ws.on("pong", () => this.live.set(ws, true)); }
+  remove(ws: WebSocket) { this.live.delete(ws); }
+  stop() { clearInterval(this.timer); }
+}
+
+/** Who a socket is and what it may join: a namespace (team, link, page), a game version and the person. */
+export interface Identity {
+  scope: string; game: string; who: Who;
+  /** a stable key for the game's saves (a file path, a page id); it must not change when the page is edited. Without it nothing is saved. */
+  slot?: string;
+}
+
+export interface SocketOptions {
+  hub: RoomHub;
+  heartbeat?: Heartbeat;
+  /** client address, for the per-address caps (after your trusted-proxy rule) */
+  address: string;
+  /** known at the upgrade (a pass cookie checked by the caller) */
+  identity?: Identity;
+  /** otherwise: the first message must be {v:1, t:"auth", ticket}; this turns the ticket into an identity, or null to refuse (4001) */
+  authenticate?: (ticket: unknown) => Promise<Identity | null> | Identity | null;
+}
+
+/**
+ * The life of one socket, as three plain callbacks for any WebSocket helper (Hono's upgradeWebSocket, uWS, ...): open(ws), message(text), close().
+ * Messages that arrive while a ticket is being checked wait (at most 8).
+ */
+export function socketEvents(o: SocketOptions) {
+  let session: Session | null = null;
+  let raw: WebSocket | null = null;
+  let waiting: string[] | null = null;
+  return {
+    open(ws: WebSocket) {
+      raw = ws;
+      o.heartbeat?.add(ws);
+      const r = o.hub.connect(connOf(ws), o.address);
+      if ("refused" in r) { ws.close(r.refused, r.reason); return; }
+      session = r;
+      if (o.identity) session.identify(o.identity.scope, o.identity.game, o.identity.who, o.identity.slot);
+    },
+    message(text: unknown) {
+      const s = session;
+      if (!s || s.dead) return;
+      const t = typeof text === "string" ? text : "";
+      if (s.who) return s.receive(t);
+      if (waiting) { if (waiting.length < 8) waiting.push(t); else s.end(CLOSE.badMessage, "too many messages before sign-in"); return; }
+      waiting = [];
+      let ticket: unknown;
+      try { const m = JSON.parse(t); ticket = m && m.v === 1 && m.t === "auth" ? m.ticket : undefined; } catch { ticket = undefined; }
+      void Promise.resolve().then(() => (o.authenticate && ticket !== undefined ? o.authenticate(ticket) : null)).catch(() => null).then((id) => {
+        if (s.dead) return;
+        if (!id) { s.end(CLOSE.notAllowed, "not allowed"); return; }
+        s.identify(id.scope, id.game, id.who, id.slot);
+        const q = waiting || [];
+        waiting = null;
+        for (const m of q) s.receive(m);
+      });
+    },
+    close() {
+      if (raw) o.heartbeat?.remove(raw);
+      session?.closed();
+    },
+  };
+}
+
+/** For a plain ws server: wire one accepted socket to the hub. */
+export function attach(ws: WebSocket, o: SocketOptions) {
+  const ev = socketEvents(o);
+  ev.open(ws);
+  ws.on("message", (data, isBinary) => ev.message(isBinary ? "" : String(data)));
+  ws.on("close", () => ev.close());
+  ws.on("error", () => { /* close follows */ });
+}
+
+/** Options for a ws WebSocketServer that fit the hub: no own size default of 100 MiB, no compression, no client list (the hub tracks sockets). */
+export const WS_OPTIONS = { noServer: true, maxPayload: 16 * 1024, perMessageDeflate: false, clientTracking: false } as const;
+
+/** Saves in memory (tests, a demo that may forget on restart). */
+export function memorySaves(): SavePort & { docs: Map<string, { at: number; data: unknown; v?: number }> } {
+  const docs = new Map<string, { at: number; data: unknown; v?: number }>();
+  const key = (scope: string, slot: string, who: string | null) => JSON.stringify([scope, slot, who]);
+  return {
+    docs,
+    async load(scope, slot, who) { const d = docs.get(key(scope, slot, who)); return d ? structuredClone(d) : null; },
+    async store(scope, slot, who, data, meta) { if (data === null) docs.delete(key(scope, slot, who)); else docs.set(key(scope, slot, who), { at: Date.now(), data: structuredClone(data), ...(meta?.v ? { v: meta.v } : {}) }); },
+  };
+}
+
+/**
+ * Saves as small JSON files in one directory (a standalone server that must keep them across restarts). File names are a hash of the key, so nothing a
+ * player or page controls reaches the path. A file written half way never replaces a good one (write to a temp name, then rename).
+ */
+export function fileSaves(dir: string): SavePort {
+  fs.mkdirSync(dir, { recursive: true });
+  const file = (scope: string, slot: string, who: string | null) => path.join(dir, crypto.createHash("sha256").update(JSON.stringify([scope, slot, who])).digest("hex").slice(0, 40) + ".json");
+  return {
+    async load(scope, slot, who) {
+      const f = file(scope, slot, who);
+      let text: string;
+      try { text = await fs.promises.readFile(f, "utf8"); } catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return null; throw e; }
+      try { const d = JSON.parse(text); if (d && typeof d.at === "number") return { at: d.at, data: d.data, ...(typeof d.v === "number" ? { v: d.v } : {}) }; } catch { /* below */ }
+      // there but not a save (a damaged file): kept aside, never deleted, and not read as an empty game
+      await fs.promises.rename(f, `${f}.bad-${Date.now()}-${crypto.randomBytes(2).toString("hex")}`).catch(() => {});
+      return null;
+    },
+    async store(scope, slot, who, data, meta) {
+      const f = file(scope, slot, who);
+      if (data === null) { await fs.promises.rm(f, { force: true }); return; }
+      const tmp = `${f}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+      // flushed to disk before the rename, so a save reported written survives a power cut on any file system
+      const fh = await fs.promises.open(tmp, "w", 0o600);
+      try { await fh.writeFile(JSON.stringify({ at: Date.now(), ...(meta?.v ? { v: meta.v } : {}), data })); await fh.sync(); } finally { await fh.close(); }
+      await fs.promises.rename(tmp, f);
+    },
+  };
+}

package/src/remote.ts

@@ -0,0 +1,236 @@
+// tickcli-js/remote: games hosted anywhere (the author's own site, a portal, GitHub Pages) play in rooms on your tickcli server.
+// The author pastes one tag; nothing else runs on their side:
+//
+//   <script src="https://rooms.example/c/dep_ab12.js" data-game="tag"></script>   <!-- relay + room.js + game.js, set up for deployment dep_ab12 -->
+//   <script> Game({ ... }) </script>
+//
+// A deployment is a public id with a list of the sites allowed to use it. The server checks the page's Origin at the socket upgrade (browsers
+// send it and page scripts cannot change it), so another site cannot run its rooms on that deployment. One kind of deployment: https sites,
+// plus http only for this machine when listed ("http://localhost:*"), so an author can test the same page from their laptop.
+// Guests: the page keeps a random 128-bit key in its own storage and sends it as the socket's first message (no cookie, so it works from any
+// site); the same key is the same seat. Each deployment is its own namespace (rooms and saves never mix) with optional caps on rooms,
+// connected players and data out.
+//
+// What this does not do: a script outside a browser can send any Origin it likes. The caps, the hub's per-address limits and revoke() are
+// the guard against that, not the origin list.
+import fs from "node:fs";
+import http from "node:http";
+import crypto from "node:crypto";
+import type { Duplex } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer, type WebSocket } from "ws";
+import { CLOSE, RoomHub, type Limits, type SavePort } from "./hub.ts";
+import { GuestPasses, Heartbeat, WS_OPTIONS, attach, clientAddress, fileSaves, gameHash } from "./node.ts";
+
+export interface Deployment {
+  /** public id, as in the page's script tag: letters, digits, "_" and "-", 3 to 64 */
+  id: string;
+  /** sites allowed to use it: "https://mygame.example", "https://mygame.example:8443", one level of wildcard subdomain
+   *  ("https://*.mygame.example") or any port (":*"). http works only for localhost, 127.0.0.1 and [::1] ("http://localhost:*" to test from a
+   *  laptop); an http entry for any other host never matches. */
+  origins: string[];
+  /** turned off: new sockets are refused (call revoke() to close its open rooms too) */
+  revoked?: boolean;
+  caps?: {
+    /** open rooms at once (default: the hub's maxRoomsPerScope) */
+    rooms?: number;
+    /** connected sockets at once */
+    players?: number;
+    /** data going out to its players, KB a second (over the last second); over it, new sockets wait (busy) and open rooms carry on */
+    kbPerSec?: number;
+  };
+}
+
+export interface RemoteOptions {
+  hub: RoomHub;
+  /** look a deployment up by id (your table, a JSON file); null or undefined = no such deployment */
+  deployment: (id: string) => Deployment | null | undefined | Promise<Deployment | null | undefined>;
+  heartbeat?: Heartbeat;
+  /** the client address after your trusted-proxy rule (default: the socket's address) */
+  address?: (req: http.IncomingMessage) => string;
+  /** socket path (default "/room") */
+  path?: string;
+}
+
+export interface Remote {
+  /** For server.on("upgrade"): true when the request was for the room socket (handled), false to leave it to you. */
+  upgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
+  /** For your request handler: serves /c/<id>.js and /client/<name>.js; true when it answered. */
+  request(req: http.IncomingMessage, res: http.ServerResponse): boolean;
+  /** Turn a deployment off now: its open rooms close (saves are written first) and its cached settings are dropped. */
+  revoke(id: string): void;
+  /** The hub namespace of a deployment (for hub.scopeStats, hub.closeScope). */
+  scope(id: string): string;
+  /** The rooms cap the hub should use for a namespace (pass to new RoomHub({ roomsPerScope })). */
+  roomsPerScope(scope: string): number | undefined;
+  /** connected sockets per deployment id */
+  sockets(id: string): number;
+}
+
+const ID_RE = /^[A-Za-z0-9_-]{3,64}$/;
+const GAME_RE = /^[A-Za-z0-9_-]{1,60}$/;
+const VER_RE = /^[A-Za-z0-9._-]{1,40}$/;
+const KEY_RE = /^[A-Za-z0-9_-]{22,64}$/;
+const LOCAL = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const CLIENT = fileURLToPath(new URL("../client/", import.meta.url));
+
+/** Is this page origin allowed for the deployment? An entry matches by scheme, host (exact, or "*." for one subdomain level) and port (exact,
+ *  or ":*" for any). https sites only, except http on this machine (localhost, 127.0.0.1, [::1]) when listed. Never "null" or a file page. */
+export function originAllowed(dep: Pick<Deployment, "origins">, origin: string | undefined): boolean {
+  if (!origin || origin === "null") return false;
+  let u: URL;
+  try { u = new URL(origin); } catch { return false; }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return false;
+  const host = u.hostname.toLowerCase();
+  if (u.protocol === "http:" && !LOCAL.has(host)) return false;
+  for (const raw of dep.origins) {
+    const m = /^(https?):\/\/(\*\.)?([a-z0-9.-]+|\[[0-9a-f:.]+\])(?::(\d{1,5}|\*))?\/?$/i.exec(raw.trim());
+    if (!m || `${m[1].toLowerCase()}:` !== u.protocol) continue;
+    const want = m[3].toLowerCase();
+    if (m[2] ? !(host.endsWith(`.${want}`) && host.length > want.length + 1) : host !== want) continue;
+    const port = m[4] === undefined ? "" : m[4] === "*" ? "*" : String(Number(m[4]) === (u.protocol === "https:" ? 443 : 80) ? "" : Number(m[4]));
+    if (port === "*" || port === u.port) return true;
+  }
+  return false;
+}
+
+/** The one-tag boot script for a deployment: relay.js, then the relay set up for this deployment, then room.js and game.js. */
+export function bootScript(id: string, sources: { relay: string; room: string; game: string }): string {
+  const boot = `;(function () {
+  var s = document.currentScript, d = (s && s.dataset) || {};
+  var base = new URL(s && s.src ? s.src : location.href);
+  var game = String(d.game || (location.pathname.split("/").pop() || "").replace(/\\.html?$/i, "") || "index").replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 60) || "index";
+  var ver = String(d.version || "1").replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 40) || "1";
+  var url = new URL("/room", base); url.protocol = base.protocol === "https:" ? "wss:" : "ws:";
+  url.searchParams.set("d", ${JSON.stringify(id)}); url.searchParams.set("game", game); url.searchParams.set("v", ver);
+  var mem = "";
+  function key() {
+    var k = "";
+    try { k = localStorage.getItem("tickcli.guest") || ""; } catch (e) { k = mem; }
+    if (!/^[A-Za-z0-9_-]{22,64}$/.test(k)) {
+      var b = new Uint8Array(16); crypto.getRandomValues(b);
+      k = btoa(String.fromCharCode.apply(null, Array.prototype.slice.call(b))).replace(/\\+/g, "-").replace(/\\//g, "_").replace(/=+$/, "");
+      try { localStorage.setItem("tickcli.guest", k); } catch (e) { mem = k; }
+    }
+    return k;
+  }
+  tickcliRelay({
+    frame: function () { return { contentWindow: window }; }, guest: true,
+    name: function () { try { return localStorage.getItem("tickcli.name") || ""; } catch (e) { return ""; } },
+    onName: function (n) { try { localStorage.setItem("tickcli.name", n); } catch (e) { /* private mode */ } },
+    connect: function () { return Promise.resolve({ url: url.href, first: { v: 1, t: "auth", ticket: key() } }); },
+  });
+})();
+`;
+  return `/* tickcli remote boot, deployment ${id}. MIT. */\n${sources.relay}\n${boot}\n${sources.room}\n;\n${sources.game}\n`;
+}
+
+export function createRemote(o: RemoteOptions): Remote {
+  const path = o.path ?? "/room";
+  const wss = new WebSocketServer({ ...WS_OPTIONS });
+  const cache = new Map<string, Deployment>();
+  const live = new Map<string, number>();
+  const src = (n: string) => fs.readFileSync(`${CLIENT}${n}.js`, "utf8");
+  const sources = { relay: src("relay"), room: src("room"), game: src("game") };
+  const files: Record<string, string> = { relay: sources.relay, room: sources.room, game: sources.game, game3d: src("game3d") };
+  const scope = (id: string) => `dep:${id}`;
+  const lookup = async (id: string) => {
+    if (!ID_RE.test(id)) return null;
+    let dep: Deployment | null | undefined = null;
+    try { dep = await o.deployment(id); } catch { dep = null; }
+    if (dep && dep.id === id) cache.set(id, dep); else cache.delete(id);
+    return dep && dep.id === id ? dep : null;
+  };
+  // refused sockets are still accepted, then closed with a code the page shows (4001 is final: the page stops trying; 1013 busy: it retries)
+  const closeWith = (req: http.IncomingMessage, socket: Duplex, head: Buffer, code: number, reason: string) =>
+    wss.handleUpgrade(req, socket, head, (ws: WebSocket) => ws.close(code, reason));
+
+  return {
+    scope,
+    sockets: (id) => live.get(id) || 0,
+    roomsPerScope: (sc) => (sc.startsWith("dep:") ? cache.get(sc.slice(4))?.caps?.rooms : undefined),
+    revoke(id) { cache.delete(id); o.hub.closeScope(scope(id), "this game was turned off by its owner"); },
+
+    upgrade(req, socket, head) {
+      const url = new URL(req.url || "/", "http://localhost");
+      if (url.pathname !== path) return false;
+      const origin = req.headers.origin;
+      if (!origin) { socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n"); return true; }
+      const id = url.searchParams.get("d") || "", game = url.searchParams.get("game") || "", ver = url.searchParams.get("v") || "1";
+      if (!GAME_RE.test(game) || !VER_RE.test(ver)) { closeWith(req, socket, head, CLOSE.badMessage, "bad game name or version"); return true; }
+      socket.on("error", () => { /* closed early */ });
+      void lookup(id).then((dep) => {
+        if (socket.destroyed) return;
+        if (!dep || dep.revoked) return closeWith(req, socket, head, CLOSE.notAllowed, "this game's deployment is unknown or turned off");
+        if (!originAllowed(dep, origin)) return closeWith(req, socket, head, CLOSE.notAllowed, `this site is not allowed for deployment ${id}`);
+        const caps = dep.caps || {}, sc = scope(id), n = live.get(id) || 0;
+        if (caps.players !== undefined && n >= caps.players) return closeWith(req, socket, head, CLOSE.busy, "this game is full right now, trying again");
+        if (caps.kbPerSec !== undefined && o.hub.scopeStats(sc).bytesOut / 1024 > caps.kbPerSec) return closeWith(req, socket, head, CLOSE.busy, "this game is busy right now, trying again");
+        wss.handleUpgrade(req, socket, head, (ws: WebSocket) => {
+          live.set(id, (live.get(id) || 0) + 1);
+          ws.on("close", () => { const left = (live.get(id) || 1) - 1; if (left > 0) live.set(id, left); else live.delete(id); });
+          attach(ws, {
+            hub: o.hub, heartbeat: o.heartbeat, address: o.address ? o.address(req) : req.socket.remoteAddress || "?",
+            // the guest key is the page's own random 128-bit value: unguessable, so nobody can take another player's seat; it names a seat in
+            // this deployment only (the hub shows others a short HMAC of it, never the key)
+            authenticate: (ticket) => typeof ticket === "string" && KEY_RE.test(ticket)
+              ? { scope: sc, game: gameHash(`${game}|${ver}`), slot: game, who: { seat: `g:${ticket}`, name: GuestPasses.defaultName(ticket), guest: true } }
+              : null,
+          });
+        });
+      });
+      return true;
+    },
+
+    request(req, res) {
+      const url = new URL(req.url || "/", "http://localhost");
+      const js = (code: number, body: string, cache = "no-store") => {
+        res.writeHead(code, { "Content-Type": "text/javascript; charset=utf-8", "Cache-Control": cache, "X-Content-Type-Options": "nosniff", "Cross-Origin-Resource-Policy": "cross-origin", "Access-Control-Allow-Origin": "*" });
+        res.end(req.method === "HEAD" ? undefined : body);
+      };
+      if (req.method !== "GET" && req.method !== "HEAD") return false;
+      const c = /^\/client\/(relay|room|game|game3d)\.js$/.exec(url.pathname);
+      if (c) { js(200, files[c[1]], "public, max-age=300"); return true; }
+      const b = /^\/c\/([^/]+)\.js$/.exec(url.pathname);
+      if (!b) return false;
+      void lookup(b[1]).then((dep) => {
+        if (!dep || dep.revoked) return js(404, `console.error(${JSON.stringify(`tickcli: no deployment ${b[1].slice(0, 64)} (unknown or turned off)`)});`);
+        js(200, bootScript(dep.id, sources), "public, max-age=300");
+      });
+      return true;
+    },
+  };
+}
+
+export interface RemoteServerOptions {
+  deployment: RemoteOptions["deployment"];
+  /** signs public player ids; keep it stable so ids stay the same across restarts (default: random per process) */
+  secret?: string;
+  /** a folder for saved profiles and worlds, or your own SavePort */
+  saves?: string | SavePort;
+  limits?: Partial<Limits>;
+  address?: RemoteOptions["address"];
+  /** behind a proxy on a private network: players' addresses from X-Forwarded-For (see clientAddress in tickcli-js/node) */
+  trustProxy?: boolean;
+}
+
+/** A complete remote room server: node:http + the hub + createRemote. Add your own routes on `server` before listen(). */
+export function createRemoteServer(o: RemoteServerOptions) {
+  let remote: Remote | null = null;
+  const saves = typeof o.saves === "string" ? fileSaves(o.saves) : o.saves;
+  const hub = new RoomHub({ secret: o.secret ?? crypto.randomBytes(32).toString("base64url"), limits: o.limits, saves, roomsPerScope: (sc) => remote?.roomsPerScope(sc) });
+  hub.start();
+  const heartbeat = new Heartbeat();
+  remote = createRemote({ hub, deployment: o.deployment, heartbeat, address: o.address ?? (o.trustProxy ? (req) => clientAddress(req, true) : undefined) });
+  const server = http.createServer((req, res) => {
+    if (remote!.request(req, res)) return;
+    res.writeHead(404, { "Content-Type": "text/plain" }); res.end("not found");
+  });
+  server.on("upgrade", (req, socket, head) => { if (!remote!.upgrade(req, socket, head)) socket.destroy(); });
+  const listen = (port = 8080, host?: string) => new Promise<string>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => { const a = server.address(); resolve(`http://${host && host !== "0.0.0.0" && host !== "::" ? host : "localhost"}:${typeof a === "object" && a ? a.port : port}/`); });
+  });
+  const close = async () => { const done = hub.shutdown(); heartbeat.stop(); server.close(); await done; };
+  return { server, hub, remote: remote!, listen, close };
+}