@zaisma/game-server 1.22.0 → 1.24.0

package/bin/node.js

@@ -26,7 +26,7 @@ import { createServer } from "node:http";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
-import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, OUTSIDE_ZAISMA_CHAT_SETTINGS, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, chatSettingsOf, checkChat, readChatMessage, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, checkedOutsidePlayer, clientIdle, defineGameServer, errorMessage, guestPlayer, newServer, isPlayerToken, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
+import { roomMessageProblem, BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, OUTSIDE_ZAISMA_CHAT_SETTINGS, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, chatSettingsOf, checkChat, readChatMessage, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, checkedOutsidePlayer, clientIdle, defineGameServer, errorMessage, guestPlayer, newServer, isPlayerToken, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
 import { OutsideCallError } from "../src/outside-calls.js";
 import { startFastLane } from "./fast-lane.js";
 import { checkedStartServerOptions, localDatabase, localRoomStates, passKeysFrom, profilesFrom, receiptKeysFrom, secretsFromEnvironment } from "./node-parts.js";
@@ -666,7 +666,7 @@ export function startServer(options) {
         const hello = JSON.parse(text ?? "");
         // A Zaisma pass, or from a game played off Zaisma, its playerToken (null for a guest).
         const isOutside = hello.pass === undefined && isPlayerToken(hello.playerToken);
-        if (hello.type !== "hello" || (typeof hello.pass !== "string" && !isOutside)) return refuse("no_hello");
+        if (hello.type !== "hello" || (typeof hello.pass !== "string" && !isOutside) || roomMessageProblem("hello", hello)) return refuse("no_hello");
         if (isOutside) playerToken = hello.playerToken;
         else pass = hello.pass;
         isSpectator = hello.isSpectator === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/sdk/zaisma.d.ts

@@ -1653,6 +1653,7 @@ declare namespace Zaisma {
    * - ended: the match is over.
    * - kept_out: the player was removed for the rest of the match.
    * - refused: the game server's canJoin turned them away.
+   * - rented_share_used: this player is on a rented-server network, and the share of the game's hosting such traffic gets is used. Zaisma's page tells them to turn off their VPN or sign in. Everyone else plays on.
    * - hosting_paused: the game's hosting on Zaisma is paused this month (its free allowance, or its developer's budget or credit, is used); new rooms open again when the month resets (UTC) or its developer adds credit, and a running match takes no new players and ends within the hour.
    * - account_needed: the player is a guest, and the game needs a Zaisma account for multiplayer or the whole game.
    * - game_not_open_to_player: the account is younger than the game's minimum age (set on the dashboard); the game never learns its age.
@@ -1684,6 +1685,7 @@ declare namespace Zaisma {
     | "kept_out"
     | "refused"
     | "hosting_paused"
+    | "rented_share_used"
     | "account_needed"
     | "game_not_open_to_player"
     | "game_unavailable"
@@ -1720,6 +1722,7 @@ declare namespace Zaisma {
    * - game_unavailable: the game can't be played right now.
    * - no_request_handler: the game's server has no onRequest.
    * - game_server_error: onRequest threw, answered something that isn't plain JSON or over 1 MB, or took over 10 seconds.
+   * - rented_share_used: this player is on a rented-server network, and the share of the game's hosting such traffic gets is used. Zaisma's page tells them to turn off their VPN or sign in. Everyone else plays on.
    * - hosting_paused: the game's hosting on Zaisma is paused this month; requests work again when the month resets (UTC) or its developer adds credit.
    * - slow_down: too many requests from this address; try again in a minute.
    * - bad_origin: the request didn't come from the game's own page.
@@ -1738,6 +1741,7 @@ declare namespace Zaisma {
     | "no_request_handler"
     | "game_server_error"
     | "hosting_paused"
+    | "rented_share_used"
     | "slow_down"
     | "bad_origin"
     | "busy";

package/sdk/zaisma.js

@@ -179,6 +179,7 @@
     return response.json().then(function (answer) {
       if (response.ok) return answer;
       var error = answer && answer.error;
+      if (error && error.code === "rented_share_used") tellRentedShareUsed();
       if (error && error.code) throw codedError(error.code, error.message);
       requestFailed();
     }, requestFailed);
@@ -218,10 +219,52 @@
     return keyPromise;
   }
 
+  /**
+   * What a Zaisma room or request hears about where this player plays from on the meter: the word /v1/pass gave beside the pass, which
+   * this SDK can't read, and two things an honest browser can say. Nothing that tells this person from anyone else. Only rooms read them.
+   */
+  var keptPlayShare = null;
+  var isInputSeen = false;
+  var graphicsChipAnswer = null;
+  function hasGraphicsChip() {
+    if (graphicsChipAnswer !== null) return graphicsChipAnswer;
+    graphicsChipAnswer = false;
+    try {
+      var webgl = document.createElement("canvas").getContext("webgl2") || document.createElement("canvas").getContext("webgl");
+      if (webgl) {
+        var rendererInfo = webgl.getExtension("WEBGL_debug_renderer_info");
+        var renderer = rendererInfo ? String(webgl.getParameter(rendererInfo.UNMASKED_RENDERER_WEBGL)) : "";
+        graphicsChipAnswer = !/swiftshader|llvmpipe|software|basic render/i.test(renderer);
+        var losing = webgl.getExtension("WEBGL_lose_context");
+        if (losing) losing.loseContext();
+      }
+    } catch (error) {
+      graphicsChipAnswer = true; // a browser that won't say counts as one that has one
+    }
+    return graphicsChipAnswer;
+  }
+  function playShareFacts() {
+    return { playShare: keptPlayShare || undefined, hasGraphicsChip: hasGraphicsChip(), isInputSeen: isInputSeen };
+  }
+  function firstInput() {
+    if (isInputSeen) return;
+    isInputSeen = true;
+    // A room told of no graphics chip and no input hears of the input now, without waiting for the game to send anything.
+    if (graphicsChipAnswer === false) joined.forEach(function (room) { if (room._ws && room._ws.readyState === 1) room._say({ type: "here" }); });
+  }
+  var FIRST_INPUTS = ["keydown", "pointerdown", "wheel", "touchstart"];
+  FIRST_INPUTS.forEach(function (type) { addEventListener(type, firstInput, { capture: true, passive: true }); });
+  addEventListener("gamepadconnected", firstInput);
+  /** Zaisma's game page says why a player on a rented network is stopped, with Sign in: only Zaisma can do that step. */
+  function tellRentedShareUsed() {
+    if (config.site && window.parent !== window) window.parent.postMessage({ type: "zaisma:rented-share-used" }, config.site);
+  }
+
   /** The pass this tab kept, while it has 10 minutes or more left, else null. */
   function keptPass() {
     try {
       var kept = JSON.parse(sessionStorage.getItem(passKey) || "null");
+      keptPlayShare = sessionStorage.getItem(passKey + ":share");
       return kept && Date.parse(kept.expiresAt) - Date.now() > 10 * 60 * 1000 ? kept : null;
     } catch (error) {
       return null; // storage off: fetch a new pass
@@ -243,7 +286,11 @@
         if (kept && kept.kind === "guest" && given.playerKind === "guest") return kept;
         return post("/v1/pass", { gameSlug: config.game, roomKey: given.key }).then(function (answer) {
           var mine = { id: answer.player.id, name: answer.player.name, kind: answer.player.kind, pass: answer.pass, expiresAt: answer.expiresAt };
-          try { sessionStorage.setItem(passKey, JSON.stringify(mine)); } catch (error) { /* fine */ }
+          keptPlayShare = answer.playShare || null;
+          try {
+            sessionStorage.setItem(passKey, JSON.stringify(mine));
+            if (keptPlayShare) sessionStorage.setItem(passKey + ":share", keptPlayShare);
+          } catch (error) { /* fine */ }
           return mine;
         });
       }, function (error) {
@@ -696,7 +743,7 @@
   };
 
   // Codes that mean this room won't take the player, so joining fails instead of trying again.
-  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "bad_player_token", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
+  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "bad_player_token", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "rented_share_used", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
 
   /**
    * Whether a Zaisma room on another version (other_version) has the page reload the game at it: on the
@@ -730,7 +777,15 @@
       room._probeIntervalSec = null;
       var hello = { type: "hello", protocolVersionNumber: PROTOCOL_VERSION_NUMBER, room: room._made, joinData: room._joinData, idleTimeoutSec: room._clientIdle.idleTimeoutSec, idleCheckEnabled: room._clientIdle.idleCheckEnabled };
       if (room._isOffZaisma) hello.playerToken = offZaisma.playerToken;
-      else hello.pass = room._pass;
+      else {
+        hello.pass = room._pass;
+        if (!room._serverUrl) {
+          var told = playShareFacts();
+          hello.playShare = told.playShare;
+          hello.hasGraphicsChip = told.hasGraphicsChip;
+          hello.isInputSeen = told.isInputSeen;
+        }
+      }
       // quickJoin's first try at a room: rather another room than one with someone this player blocked.
       if (room._avoidsBlockedPlayers) hello.avoidBlockedPlayers = true;
       // Any quickJoin: Zaisma learns the game joins players by itself, for its Rooms tab.
@@ -860,6 +915,7 @@
         window.parent.postMessage(room._spectating({ type: "zaisma:reload", code: room.roomCode, versionId: message.versionId }), config.site);
       } else if (message.type === "error") {
         room._emit("error", { code: message.code, message: message.message });
+        if (message.code === "rented_share_used") tellRentedShareUsed();
         if (room._ready && REFUSED.indexOf(message.code) !== -1) {
           room._done = true;
           room._ready.reject(codedError(message.code, message.message));
@@ -1840,7 +1896,11 @@
     var base = (serverUrl || config.rooms).replace(/^ws/, "http");
     var isOffZaisma = !config.rooms;
     // Off Zaisma there's no pass: the playerToken goes in its place.
-    var sender = isOffZaisma ? Promise.resolve({ playerToken: offZaisma.playerToken }) : getPass().then(function (mine) { return { pass: mine.pass }; });
+    var sender = isOffZaisma ? Promise.resolve({ playerToken: offZaisma.playerToken }) : getPass().then(function (mine) {
+      if (serverUrl) return { pass: mine.pass };
+      var told = playShareFacts();
+      return { pass: mine.pass, playShare: told.playShare, hasGraphicsChip: told.hasGraphicsChip, isInputSeen: told.isInputSeen };
+    });
     return sender.then(function (who) {
       who.request = JSON.parse(requestText);
       return fetch(base + "/v1/requests/" + (isOffZaisma ? offZaisma.gameSlug : config.game), { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify(who) }).then(answered, requestFailed);

package/src/doors.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Door contracts (docs/DOORS.md). Every way into Zaisma, of every kind, states who may call it, what it may
+ * reach and what it trusts from other doors, and goes through checkDoor before its own code runs. Here, in the
+ * game server package's internal part, so a room on a developer's own server goes through the same check;
+ * never in the package's published index.
+ */
+/** Callers the door's guard proves itself, from what it read of the request or the room. */
+export type DoorCallerProvenByGuard = 
+/** Guests too. A door that shows a signed-in person more trusts `session` as well. */
+"anyone"
+/** A session that works. */
+ | "signed_in"
+/** A session with a finished account, and no developer ban unless the door keeps it open to them. */
+ | "developer"
+/** Cloudflare Access to /admin. */
+ | "admin"
+/** Anyone in the room, spectators too. */
+ | "room_member"
+/** A player in the room, not a spectator. */
+ | "room_player"
+/** The room's host. */
+ | "room_host";
+/** Callers a named function proves, because the proof takes the door's own data (a body's signature, a token's row). */
+export type DoorCallerProvenByFunction = 
+/** The API router: an API key's access, or a session from Zaisma's own pages. */
+"api_caller"
+/** A tester or preview link's token in the address. */
+ | "link_holder"
+/** A Sign in with Zaisma code or access token. */
+ | "token_holder"
+/** Stripe or GitHub, by the signature on the body. */
+ | "signed_sender"
+/** A game's own page, by the request's Origin. */
+ | "game_page"
+/** A signed player pass. */
+ | "pass_holder";
+export type DoorCaller = DoorCallerProvenByGuard | DoorCallerProvenByFunction;
+/**
+ * What a door may touch. The first seven are the API's own words (ApiRoute's reaches, apps/site/src/developer.ts):
+ * `account`, `player_save`, `game`, `webhook`, `sign_in_app` and `forum_topic` are the caller's own or what the caller may read,
+ * and `nothing_private` is what anyone may see. The `any_` ones and `zaisma_settings` are only ever an admin's.
+ */
+export type DoorReach = "account" | "player_save" | "game" | "webhook" | "sign_in_app" | "forum_topic" | "nothing_private" | "any_game" | "any_account" | "zaisma_settings" | "room" | "purchase";
+/** What a door takes from another door, as the security map names them (scripts/security-map/doors.mjs). */
+export type DoorTrust = "session" | "api_key" | "oauth_code" | "oauth_access" | "tester_link" | "preview_link" | "player_pass" | "admin_access" | "player_id" | "stripe_signature" | "github_signature" | "game_origin" | "purchase_receipt" | "passkey" | "email_code";
+/** The function that proves a caller; a test checks it exists. */
+export interface DoorProof {
+    source_path: string;
+    symbol_name: string;
+}
+/**
+ * What a door takes, as the small part of JSON Schema Zaisma's schemas use. Only the helpers below make one, and each
+ * takes its bound, so "accepts anything" can't be stated. Only a game's own data goes by size alone, at the caps it has.
+ */
+export type DoorShape = Readonly<Record<string, unknown>> & {
+    readonly [SHAPE_MARK]: true;
+};
+declare const SHAPE_MARK: unique symbol;
+export declare const text: (maximumCharacterCount: number, pattern?: string) => DoorShape;
+export declare const oneOfWords: (...words: readonly string[]) => DoorShape;
+export declare const integer: (minimumNumber?: number, maximumNumber?: number) => DoorShape;
+export declare const realNumber: (minimumNumber: number, maximumNumber: number) => DoorShape;
+export declare const yesOrNo: DoorShape;
+export declare const anyOf: (...shapes: readonly DoorShape[]) => DoorShape;
+export declare const orNothing: (shape: DoorShape) => DoorShape;
+export declare const listOf: (items: DoorShape, maximumItemCount: number, minimumItemCount?: number) => DoorShape;
+/** A closed object: these fields and no others, the required ones named. */
+export declare const fieldsOf: (properties: Readonly<Record<string, DoorShape>>, required?: readonly string[]) => DoorShape;
+/** A game's own data, of any shape: its size only, in characters of its JSON. */
+export declare const gameData: (maximumSizeBytes: number) => DoorShape;
+/** A door's body, when it takes one. maximumSizeBytes is checked before any of it is read; raw bytes go by size alone, and the door reads them itself. */
+export type DoorBody = {
+    kind: "json";
+    fields: Readonly<Record<string, DoorShape>>;
+    required?: readonly string[];
+    maximumSizeBytes: number;
+    isOptional?: true;
+} | {
+    kind: "form";
+    fields: Readonly<Record<string, DoorShape>>;
+    fileNames?: readonly string[];
+    maximumSizeBytes: number;
+} | {
+    kind: "bytes";
+    maximumSizeBytes: number;
+};
+/** What a door takes: its query's names and its body. A query's values arrive as text: integer and boolean shapes read theirs. */
+export interface DoorTakes {
+    query: Readonly<Record<string, DoorShape>>;
+    body: DoorBody | null;
+}
+/** Nothing: a door with no query it reads and no body. */
+export declare const TAKES_NOTHING: DoorTakes;
+/** What a door answers: a JSON schema, checked on live requests and cut to what it declares, or a kind with nothing to cut. */
+export type DoorAnswer = {
+    kind: "json";
+    schema: Readonly<Record<string, unknown>>;
+} | {
+    kind: "page" | "empty" | "redirect" | "file" | "bytes";
+};
+export declare const ANSWERS_PAGE: DoorAnswer;
+export declare const ANSWERS_EMPTY: DoorAnswer;
+export declare const ANSWERS_REDIRECT: DoorAnswer;
+export declare const ANSWERS_FILE: DoorAnswer;
+export declare const ANSWERS_BYTES: DoorAnswer;
+export declare const answersJson: (schema: Readonly<Record<string, unknown>>) => DoorAnswer;
+/** A door's limit in calls a minute, from this short list. Each is a rate limit binding in the Workers that use it: LIMIT_<LEVEL>. */
+export declare const DOOR_LIMIT_LEVELS: {
+    readonly very_rare: 2;
+    readonly guess: 5;
+    readonly rare: 10;
+    readonly steady: 30;
+    readonly busy: 120;
+    readonly building: 1000;
+};
+export type DoorLimitLevel = keyof typeof DOOR_LIMIT_LEVELS;
+/** Why a door has no limit of its own: from this list only, and the daily review reads every door that gives one. */
+export declare const DOOR_NO_LIMIT_REASONS: {
+    readonly answers_from_memory: "It answers fixed bytes from memory and reads nothing.";
+    readonly cached_file: "It serves a file Cloudflare caches, with no database behind it and no egress fee.";
+    readonly admin_only: "Cloudflare Access stands in front of it, and only Zaisma's own people get through.";
+    readonly signed_by_sender: "It reads nothing until the sender's signature on the body checks out.";
+    readonly counted_by_its_call: "All it does is make calls that have their own limit.";
+    readonly room_token_bucket: "A room's message bucket takes a token for each message, per player, before any door runs.";
+};
+export type DoorNoLimitReason = keyof typeof DOOR_NO_LIMIT_REASONS;
+/**
+ * How much a door can be used. A limit counts the player, the account or the game wherever Zaisma knows it, and an
+ * address only before it knows, at the level a whole building clears, so 25 players on one school's wifi play like
+ * anyone. group shares one counter between doors; with none, each door counts on its own.
+ */
+export type DoorLimit = {
+    level: DoorLimitLevel;
+    counts: "player" | "account" | "game";
+    group?: string;
+} | {
+    level: "building";
+    counts: "address";
+    group?: string;
+} | {
+    whyNoLimit: DoorNoLimitReason;
+};
+export interface DoorContractFields {
+    reaches: DoorReach;
+    trusts: readonly DoorTrust[];
+    takes: DoorTakes;
+    answers: DoorAnswer;
+    limit: DoorLimit;
+}
+/** A caller a function proves can't be stated without naming the function, so it doesn't build. */
+export type DoorContract = DoorContractFields & ({
+    whoMayCall: DoorCallerProvenByGuard;
+} | {
+    whoMayCall: DoorCallerProvenByFunction;
+    provenBy: DoorProof;
+});
+/** A Worker's rate limit bindings, by level. A self-hosted room has none, and a missing one lets the call through. */
+/** A rate limit binding, as Workers gives one. */
+export interface DoorLimitBinding {
+    limit(options: {
+        key: string;
+    }): Promise<object>;
+}
+export type DoorLimitBindings = {
+    [Level in DoorLimitLevel as `LIMIT_${Uppercase<Level>}`]?: DoorLimitBinding;
+};
+/** Whether a call goes past a level's limit: door's own counter, for one subject. Keys never leave Cloudflare's counter. */
+export declare function isPastLevel(env: DoorLimitBindings, level: DoorLimitLevel, counterName: string, subject: string): Promise<boolean>;
+/** Whether a call goes past a door's limit. doorName names its counter unless its limit shares a group. */
+export declare function isPastDoorLimit(env: DoorLimitBindings, limit: DoorLimit, doorName: string, subject: string): Promise<boolean>;
+type Schema = Readonly<Record<string, unknown>>;
+/** Where a value doesn't match its shape or schema, as "path: problem" lines; [] when it fits. Answers and inputs both come here. */
+export declare function schemaProblems(schema: Schema, given: unknown, path?: string): string[];
+/** Where a value's types don't match a schema; null reads as left out, and what a call behind it allows, names included, stays the call's to say, with its own fix. */
+export declare function typeProblems(schema: Schema, given: unknown, path?: string): string[];
+/**
+ * An answer with every field its schema didn't declare taken out, and the paths it took (a list's index as []): the
+ * caller still gets the answer. Nothing else changes, and an answer with nothing to cut comes back as the same value.
+ * Only closed objects cut, so a game's own rows and arguments pass as they are.
+ */
+export declare function cutUndeclared(schema: Schema, given: unknown, path?: string): {
+    kept: unknown;
+    cutPaths: string[];
+};
+/** The first problem with a query, as [name, what's wrong], or null. isOpenToOtherNames: a page ignores names it doesn't read, since share links pick some up. */
+export declare function queryProblem(fields: Readonly<Record<string, DoorShape>>, query: URLSearchParams, isOpenToOtherNames?: boolean): {
+    field: string;
+    problem: string;
+} | null;
+/** The first problem with a JSON body's fields: closed, each field its shape, the required ones there. */
+export declare function bodyProblem(fields: Readonly<Record<string, DoorShape>>, required: readonly string[], body: Readonly<Record<string, unknown>>): {
+    field: string;
+    problem: string;
+} | null;
+/** The first problem with a form's fields: its names closed, each value text, or a list where it may repeat. A form's text boxes send what they send, so its numbers are the door's to read. */
+export declare function formProblem(fields: Readonly<Record<string, DoorShape>>, fileNames: readonly string[], form: {
+    keys(): IterableIterator<string>;
+    getAll(name: string): unknown[];
+}): {
+    field: string;
+    problem: string;
+} | null;
+/**
+ * The one check every door goes through. `proven` is who the door's guard found the caller to be; a caller a
+ * named function proves passes here, and that function refuses them, before anything else of the door runs.
+ */
+export declare function checkDoor(contract: DoorContract, proven: readonly DoorCaller[]): boolean;
+/** Where a door's path parts come from: `:name` parts, each a [^/]+ unless named here, and a final `*` for the rest. */
+export declare function doorPathPattern(path: string, partPatterns?: Readonly<Record<string, string>>): RegExp;
+export {};