@zaisma/game-server 1.3.0 → 1.5.0

package/bin/local-play-bench.d.ts

@@ -0,0 +1,8 @@
+/** What the dev page's frame lets the player's page pass on to the game: the game page's own list. */
+export const FRAME_ALLOW: string;
+/** The dev page's script. */
+export function devScriptSource(): string;
+/** The end of a sign-in on the bench (/account/kept). */
+export const KEPT_SCRIPT_SOURCE: string;
+/** Where a tab arrives: its own player number again, or a new player's. */
+export const ARRIVE_SCRIPT_SOURCE: string;

package/bin/local-play-bench.js

@@ -0,0 +1,218 @@
+// The dev page's own scripts (local-play.js serves them as /bench/dev.js and /bench/kept.js). The dev page is the bench's: its bar
+// (bench/glass.ts) and one frame, the player's page, which is zaisma.com's game page with its own scripts. These never reach into it.
+
+/** What the dev page's frame lets the player's page pass on to the game: the game page's own list (apps/site/src/pages.ts; test/node/local-play-parity.test.ts holds the two together). */
+export const FRAME_ALLOW = "fullscreen; gamepad; autoplay; web-share; clipboard-write; cross-origin-isolated";
+
+/** The dev page's script: it keeps the player's place, reloads the game when a file changes, runs the dev bar's menus and the Players panel. */
+export const devScriptSource = () => `(${devScript.toString()})();\n`;
+
+/**
+ * The end of a sign-in on the bench (/account/kept): it tells the open game pages, as zaisma.com's own page does. Opened as a tab of its own,
+ * it closes; reached in the player's own tab (a blocked pop-up sends the sign-in there), it goes back to the player's dev page and game.
+ */
+export const KEPT_SCRIPT_SOURCE = `try { new BroadcastChannel("zaisma").postMessage("signed-in"); } catch {}
+var keptPlayerNumber = Number(new URL(document.currentScript.src).searchParams.get("player")) || 0;
+setTimeout(function () {
+  if (window.opener) window.close();
+  else location.replace(keptPlayerNumber ? "/?player=" + keptPlayerNumber : "/");
+}, 800);
+`;
+
+/** Where a tab arrives (/ with no player): the tab's own player number again, or a new player's, then the dev page. */
+export const ARRIVE_SCRIPT_SOURCE = `(function () {
+  var kept = null;
+  try { kept = Number(sessionStorage.getItem("zaisma-bench:player")) || null; } catch (error) {}
+  var room = /^[A-Z0-9]{6}$/.test(new URLSearchParams(location.search).get("room") || "") ? new URLSearchParams(location.search).get("room") : null;
+  fetch("/bench/claim", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ keptPlayerNumber: kept }) })
+    .then(function (response) { return response.json(); })
+    .then(function (answer) { location.replace("/?player=" + answer.playerNumber + (room ? "&room=" + room : "")); });
+})();
+`;
+
+/** Run in the browser. Written as a function so it stays real code; the bench serves its text. */
+function devScript() {
+  const scriptUrl = new URL(document.currentScript.src);
+  const isPage = scriptUrl.searchParams.get("page") === "players";
+  let playerNumber = Number(scriptUrl.searchParams.get("player")) || 0;
+  try {
+    // The Players page a sign-in opened knows its player from the tab (a tab opened by a page starts with a copy of the page's storage).
+    if (isPage && !playerNumber) playerNumber = Number(sessionStorage.getItem("zaisma-bench:player")) || 0;
+    else sessionStorage.setItem("zaisma-bench:player", String(playerNumber));
+  } catch {
+    // Storage off: the tab is a new player each time it comes to /.
+  }
+  const frame = document.getElementById("bench-player");
+  const panel = document.getElementById("bench-panel");
+  const playersButton = document.getElementById("bench-players-open");
+  const addTab = document.getElementById("bench-add-tab");
+  let reloadNumber = null;
+  let roomCode = null;
+
+  const refresh = (name) =>
+    fetch(`/bench/sheet/${name}?player=${playerNumber}`)
+      .then((response) => response.text())
+      .then((text) => {
+        const body = document.getElementById(`bench-${name}-body`);
+        if (body) body.innerHTML = text;
+      })
+      .catch(() => {});
+
+  // --- The Players panel: drawn by the bench, and every change through the bench's API, the same calls a developer's AI makes ---
+  let panelView = { view: "list", playerId: "", tab: "profile", search: "" };
+  const drawPanel = (changes = {}) => {
+    panelView = { ...panelView, ...changes };
+    const query = new URLSearchParams({ player: String(playerNumber), view: panelView.view, player_id: panelView.playerId, tab: panelView.tab, search: panelView.search, page: isPage ? "yes" : "" });
+    return fetch(`/bench/panel?${query}`)
+      .then((response) => response.text())
+      .then((text) => {
+        panel.innerHTML = text;
+        const search = panel.querySelector("[data-bench-search]");
+        if (search && panelView.search) {
+          search.focus();
+          search.setSelectionRange(search.value.length, search.value.length);
+        }
+      })
+      .catch(() => {});
+  };
+  const showPanel = (isShown) => {
+    if (!panel || isPage) return;
+    panel.hidden = !isShown;
+    playersButton?.setAttribute("aria-pressed", String(isShown));
+    if (isShown) drawPanel();
+  };
+  const api = (method, path, body) =>
+    fetch(path, { method, headers: { "content-type": "application/json" }, ...(method === "GET" || method === "DELETE" ? {} : { body: JSON.stringify(body ?? {}) }) }).then(async (response) => ({ isOk: response.ok, answer: await response.json().catch(() => ({})) }));
+  const showError = (answer) => {
+    const line = panel.querySelector("[data-bench-error]");
+    if (line && answer?.error) {
+      line.textContent = answer.error.message;
+      line.hidden = false;
+    }
+  };
+  // Playing as someone starts the game again as them: here the dev page comes back with the game; on the page a sign-in opened, the
+  // game page hears it as zaisma.com's own end of a sign-in, and the page closes or goes back to the player's game.
+  const playAs = (playerId) =>
+    api("PUT", `/bench/api/open-players/${playerNumber}`, { player_id: playerId === "guest" ? null : playerId }).then(({ isOk }) => {
+      if (!isOk) return;
+      if (!isPage) return location.assign(`/?player=${playerNumber}`);
+      try {
+        new BroadcastChannel("zaisma").postMessage("signed-in");
+      } catch {
+        // No channel: the game page checks again as its tab comes back into view.
+      }
+      if (window.opener) window.close();
+      else location.assign(`/?player=${playerNumber}`);
+    });
+  if (panel) {
+    panel.addEventListener("click", (event) => {
+      const target = event.target instanceof Element ? event.target : null;
+      const closer = target?.closest("[data-bench-panel]");
+      if (closer) return showPanel(false);
+      const viewer = target?.closest("[data-bench-view]");
+      if (viewer) return drawPanel({ view: viewer.dataset.benchView, playerId: viewer.dataset.playerId ?? panelView.playerId, tab: "profile", search: "" });
+      const tab = target?.closest("[data-bench-tab]");
+      if (tab) return drawPanel({ tab: tab.dataset.benchTab, search: "" });
+      const caller = target?.closest("[data-bench-call]");
+      if (caller) {
+        const [method, path] = caller.dataset.benchCall.split(" ");
+        return api(method, path, JSON.parse(caller.dataset.benchBody || "{}")).then(({ isOk, answer }) => (isOk ? drawPanel() : showError(answer)));
+      }
+      const maker = target?.closest("[data-bench-make]");
+      if (maker) {
+        const form = maker.closest("[data-bench-form]");
+        const field = (name) => form.querySelector(`[name="${name}"]`).value;
+        return api("POST", "/bench/api/players", { name: field("name"), age_band: field("age_band"), social_mode: field("social_mode") }).then(({ isOk, answer }) =>
+          isOk ? drawPanel({ view: "player", playerId: answer.player.player_id, tab: "profile", search: "" }) : showError(answer),
+        );
+      }
+      const deleter = target?.closest("[data-bench-delete]");
+      if (deleter && confirm(`Delete ${deleter.dataset.playerName}? Their saves, items, purchases, friends and blocks on the bench go too.`)) {
+        return api("DELETE", deleter.dataset.benchDelete).then(() => drawPanel({ view: "list", playerId: "" }));
+      }
+    });
+    // A profile's fields save as they change; picking a friend or a block adds them.
+    panel.addEventListener("change", (event) => {
+      const field = event.target;
+      if (!(field instanceof HTMLInputElement || field instanceof HTMLSelectElement)) return;
+      if (field.dataset.benchField) {
+        api("PATCH", field.dataset.benchField, { [field.name]: field.value }).then(({ isOk, answer }) => (isOk ? drawPanel() : showError(answer)));
+      } else if (field.dataset.benchAdd && field.value) {
+        api("PUT", `${field.dataset.benchAdd}${field.value}`).then(({ isOk, answer }) => (isOk ? drawPanel() : showError(answer)));
+      }
+    });
+    let searchTimer = null;
+    panel.addEventListener("input", (event) => {
+      if (!(event.target instanceof HTMLInputElement) || !event.target.hasAttribute("data-bench-search")) return;
+      const search = event.target.value;
+      clearTimeout(searchTimer);
+      searchTimer = setTimeout(() => drawPanel({ search }), 200);
+    });
+  }
+  playersButton?.addEventListener("click", () => showPanel(panel.hidden));
+
+  // --- The dev bar's menus: each opens under its button, drawn afresh where it shows what changes, and closes on a pick, Escape or a click away ---
+  const closeMenus = () => {
+    for (const menu of document.querySelectorAll(".bench-menu")) menu.hidden = true;
+    for (const button of document.querySelectorAll("[data-bench-menu]")) button.setAttribute("aria-expanded", "false");
+  };
+  const openMenu = (button) => {
+    const menu = document.getElementById(button.dataset.benchMenu);
+    const wasOpen = !menu.hidden;
+    closeMenus();
+    if (wasOpen) return;
+    menu.hidden = false;
+    const buttonBox = button.getBoundingClientRect();
+    menu.style.left = `${Math.max(8, Math.min(buttonBox.left, innerWidth - menu.offsetWidth - 8))}px`;
+    button.setAttribute("aria-expanded", "true");
+    if (menu.id === "bench-add-menu") refresh("phone");
+    if (menu.id === "bench-log-menu") refresh("log");
+    menu.querySelector(".bm-item")?.focus();
+  };
+  document.addEventListener("click", (event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const menuButton = target?.closest("[data-bench-menu]");
+    if (menuButton) return openMenu(menuButton);
+    // Playing as someone, from the player menu or the Players panel.
+    const player = target?.closest("[data-bench-play-as]");
+    if (player) {
+      closeMenus();
+      return playAs(player.dataset.benchPlayAs);
+    }
+    // The player menu's All players opens the panel.
+    const opener = target?.closest('[data-bench-panel="open"]');
+    if (opener) {
+      event.preventDefault();
+      closeMenus();
+      return showPanel(true);
+    }
+    if (target?.closest(".bm-item")) return setTimeout(closeMenus, 0);
+    if (!target?.closest(".bench-menu")) closeMenus();
+  });
+  addEventListener("keydown", (event) => {
+    if (event.key === "Escape") closeMenus();
+  });
+  if (isPage) {
+    drawPanel();
+    return;
+  }
+
+  // About once a second: the player is still here, a game file changed (reload the game), and the room they're in (Add a player joins it).
+  const check = () =>
+    fetch(`/bench/state?player=${playerNumber}`)
+      .then((response) => response.json())
+      .then((answer) => {
+        if (reloadNumber !== null && answer.reloadNumber !== reloadNumber) frame.contentWindow?.location.reload();
+        reloadNumber = answer.reloadNumber;
+        if (answer.roomCode !== roomCode) {
+          roomCode = answer.roomCode;
+          // A new tab is a new player (a link to a new tab starts with nothing of this one's), into this room.
+          addTab.href = roomCode ? `/?room=${roomCode}` : "/";
+        }
+      })
+      .catch(() => {});
+  check();
+  setInterval(check, 1000);
+  addEventListener("pagehide", () => navigator.sendBeacon(`/bench/leave?player=${playerNumber}`));
+  if (new URLSearchParams(location.search).get("panel") === "players") showPanel(true);
+}

package/bin/local-play-certificate.js

@@ -0,0 +1,99 @@
+// The test bench's own HTTPS certificate (local-play.js uses it with --on-network): self-signed, made on this computer for its own
+// names and addresses, so a phone that asks for HTTPS gets it. No one vouches for it, so the phone warns once before it opens the bench.
+// Written with Node's crypto alone (an EC key, and the certificate's DER put together here), so the package needs no dependency for it.
+import { X509Certificate, createPrivateKey, generateKeyPairSync, randomBytes, sign } from "node:crypto";
+import { isIP } from "node:net";
+
+/** How long a certificate lasts: under the 398 days browsers take, and made again before it ends. */
+const CERTIFICATE_DURATION_DAYS = 397;
+const DAY_MS = 24 * 3600 * 1000;
+
+// DER, the encoding certificates are written in: a tag, the length, then the bytes.
+function der(tag, content) {
+  const contentSizeBytes = content.length;
+  const lengthBytes = contentSizeBytes < 128 ? [contentSizeBytes] : contentSizeBytes < 256 ? [0x81, contentSizeBytes] : [0x82, contentSizeBytes >> 8, contentSizeBytes & 0xff];
+  return Buffer.concat([Buffer.from([tag, ...lengthBytes]), content]);
+}
+const sequence = (...parts) => der(0x30, Buffer.concat(parts));
+const set = (...parts) => der(0x31, Buffer.concat(parts));
+const explicit = (tagNumber, content) => der(0xa0 + tagNumber, content);
+const octets = (bytes) => der(0x04, bytes);
+const bits = (bytes) => der(0x03, Buffer.concat([Buffer.from([0]), bytes]));
+const utf8 = (text) => der(0x0c, Buffer.from(text, "utf8"));
+function integer(bytes) {
+  // A positive integer: a leading zero byte when the first bit is set.
+  return der(0x02, bytes[0] & 0x80 ? Buffer.concat([Buffer.from([0]), bytes]) : bytes);
+}
+function objectId(dotted) {
+  const [first, second, ...rest] = dotted.split(".").map(Number);
+  const bytes = [first * 40 + second];
+  for (const part of rest) {
+    const groups = [];
+    let remaining = part;
+    do {
+      groups.unshift(remaining & 0x7f);
+      remaining = Math.floor(remaining / 128);
+    } while (remaining > 0);
+    bytes.push(...groups.map((groupNumber, groupIndex) => (groupIndex < groups.length - 1 ? groupNumber | 0x80 : groupNumber)));
+  }
+  return der(0x06, Buffer.from(bytes));
+}
+function utcTime(atMs) {
+  const shown = new Date(atMs).toISOString();
+  return der(0x17, Buffer.from(`${shown.slice(2, 4)}${shown.slice(5, 7)}${shown.slice(8, 10)}${shown.slice(11, 13)}${shown.slice(14, 16)}${shown.slice(17, 19)}Z`, "ascii"));
+}
+/** An address as subjectAltName writes it: 4 bytes for IPv4, 16 for IPv6. */
+function addressBytes(address) {
+  if (isIP(address) === 4) return Buffer.from(address.split(".").map(Number));
+  const halves = address.split("::");
+  const groupsOf = (text) => (text ? text.split(":") : []);
+  const head = groupsOf(halves[0]);
+  const tail = groupsOf(halves[1] ?? "");
+  const groups = [...head, ...Array(8 - head.length - tail.length).fill("0"), ...tail];
+  return Buffer.from(groups.flatMap((group) => [parseInt(group, 16) >> 8, parseInt(group, 16) & 0xff]));
+}
+
+/**
+ * A self-signed certificate for these names and addresses ("localhost", "192.168.1.20"), with its key, as PEM text:
+ * { certificatePem, keyPem }. ECDSA P-256 and SHA-256, for server authentication, as phones ask of a server's certificate.
+ */
+export function makeCertificate(names, nowMs = Date.now()) {
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const name = sequence(set(sequence(objectId("2.5.4.3"), utf8("Zaisma test bench"))));
+  const signatureAlgorithm = sequence(objectId("1.2.840.10045.4.3.2"));
+  const alternativeNames = sequence(...names.map((each) => (isIP(each) ? der(0x87, addressBytes(each)) : der(0x82, Buffer.from(each, "ascii")))));
+  const extensions = explicit(3, sequence(
+    sequence(objectId("2.5.29.17"), octets(alternativeNames)),
+    // Extended key usage: server authentication.
+    sequence(objectId("2.5.29.37"), octets(sequence(objectId("1.3.6.1.5.5.7.3.1")))),
+    // Basic constraints: not a certificate authority.
+    sequence(objectId("2.5.29.19"), octets(sequence())),
+  ));
+  const serial = randomBytes(16);
+  serial[0] &= 0x7f;
+  const toBeSigned = sequence(
+    explicit(0, integer(Buffer.from([2]))),
+    integer(serial),
+    signatureAlgorithm,
+    name,
+    sequence(utcTime(nowMs - DAY_MS), utcTime(nowMs + CERTIFICATE_DURATION_DAYS * DAY_MS)),
+    name,
+    publicKey.export({ type: "spki", format: "der" }),
+    extensions,
+  );
+  const certificate = sequence(toBeSigned, signatureAlgorithm, bits(sign("sha256", toBeSigned, privateKey)));
+  const lines = certificate.toString("base64").match(/.{1,64}/g) ?? [];
+  return { certificatePem: `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----\n`, keyPem: privateKey.export({ type: "pkcs8", format: "pem" }) };
+}
+
+/** Whether a kept certificate still serves: it reads, covers every one of these names, and has more than a week left. */
+export function isCertificateGood(kept, names, nowMs = Date.now()) {
+  try {
+    const certificate = new X509Certificate(kept.certificatePem);
+    createPrivateKey(kept.keyPem);
+    const covers = (each) => (isIP(each) ? certificate.checkIP(each) : certificate.checkHost(each)) !== undefined;
+    return Date.parse(certificate.validTo) - nowMs > 7 * DAY_MS && names.every(covers);
+  } catch {
+    return false;
+  }
+}

package/bin/local-play-runner.js

@@ -0,0 +1,43 @@
+// The game server of the local bench (local-play.js), as a process of its own: a change to the game server's files
+// stops this process (every room saves first) and starts a new one, so the new code is read from scratch.
+// Not a command: local-play.js starts it with one JSON argument and hears ZAISMA_LOCAL_RUNNER_READY when it listens.
+import { createServer } from "node:net";
+import { pathToFileURL } from "node:url";
+import { relay } from "../src/internal.js";
+import { localDatabase } from "./node-parts.js";
+import { startServer } from "./node.js";
+
+const config = JSON.parse(process.argv[2] ?? "{}");
+try {
+  // Said plainly before anything listens: the runner's own listen error would end this process with a stack trace.
+  await new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.once("error", (error) => reject(error?.code === "EADDRINUSE" ? new Error(`Port ${config.port} is already in use, so your game server can't start. Stop what's using it, or start the bench with another --port.`) : error));
+    probe.listen(config.port, () => probe.close(resolve));
+  });
+  const gameServer = config.entry ? (await import(pathToFileURL(config.entry).href)).default : relay;
+  const running = startServer({
+    gameServer,
+    gameSlug: config.gameSlug,
+    port: config.port,
+    origins: [config.origin],
+    issuerUrl: config.issuerUrl,
+    database: localDatabase(config.databaseFile),
+    roomStateFile: config.roomStateFile,
+    // onPurchase and onRefund hear purchases through the stand-in developer API on the bench's rooms.
+    zaismaKey: config.zaismaKey,
+    developerApiUrl: config.developerApiUrl,
+  });
+  let stopping = null;
+  const stop = () => (stopping ??= running.close().then(() => process.exit(0)));
+  for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, stop);
+  // The bench holds this pipe open while it runs: when it ends, however it ended, this game server stops too (rooms save first).
+  process.stdin.once("close", stop);
+  process.stdin.resume();
+  const isListening = () => console.log("ZAISMA_LOCAL_RUNNER_READY");
+  if (running.httpServer.listening) isListening();
+  else running.httpServer.once("listening", isListening);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}

package/bin/local-play.d.ts

@@ -0,0 +1,41 @@
+/** What startLocalPlay takes. Only gameFolder is required; the rest have the defaults named here. */
+export interface LocalPlayOptions {
+  /** The folder of your game, the one with index.html at the top. Its game server is zaisma-server/index.js or zaisma-server.js, else the relay. */
+  gameFolder: string;
+  /** The first of four ports: the bench, the game's site, the stand-in rooms and your game server take it and the next three. Default 4800. */
+  port?: number;
+  /** Listen on every address, so a phone on the same Wi-Fi can open the bench. Default false: this computer only. */
+  isOnNetwork?: boolean;
+  /** Your game's Zaisma slug. Default: the folder's name. */
+  gameSlug?: string | null;
+  /** An API key; with gameSlug, each start brings in the game's items from Zaisma. Default: the ZAISMA_KEY environment variable. */
+  zaismaKey?: string;
+  /** Zaisma's developer API, where that copy is read from. Default: https://zaisma.com/api/dev. */
+  developerApiUrl?: string;
+  /** Where lines of text go. Default: the terminal. */
+  log?: (line: string) => void;
+}
+
+export interface LocalPlay {
+  /** The test bench's address, on this computer. */
+  benchUrl: string;
+  gameSiteUrl: string;
+  roomsUrl: string;
+  /** The bench's address for a phone on the same Wi-Fi; null without isOnNetwork. */
+  networkUrl: string | null;
+  /** How many times the game server has been started: more than one after a change to its files. */
+  readonly runnerStartCount: number;
+  /** Saves every room, then stops everything. */
+  close(): Promise<void>;
+}
+
+export const DEFAULT_PORT_NUMBER: number;
+export const LOCAL_VERSION_ID: string;
+export const LOCAL_FOLDER: string;
+export const SERVED_ZAISMA_PATHS: string[];
+export const ONLY_ON_ZAISMA_PATHS: string[];
+export function startLocalPlay(options: LocalPlayOptions): Promise<LocalPlay>;
+export function serverEntryOf(gameFolder: string): string | null;
+export function withScripts(page: string, scriptUrls: string[]): string;
+export function localGameHeaders(contentType: string, benchOrigin: string, connectOrigins: string[]): Record<string, string>;
+export function terminalQr(text: string): string;