@zaisma/game-server 1.22.0 → 1.23.0

package/package.json

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

package/src/doors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;
+}
+export interface DoorContractFields {
+    reaches: DoorReach;
+    trusts: readonly DoorTrust[];
+}
+/** 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;
+});
+/**
+ * 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;

package/src/doors.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function checkDoor(contract, proven) {
+    return contract.whoMayCall === "anyone" || "provenBy" in contract || proven.includes(contract.whoMayCall);
+}
+/** Where a door's path parts come from: `:name` parts, each a [^/]+ unless named here, and a final `*` for the rest. */
+export function doorPathPattern(path, partPatterns = {}) {
+    const parts = path.split("/").map((part) => {
+        if (part === "*")
+            return ".*";
+        if (part.startsWith(":"))
+            return `(?<${part.slice(1)}>${partPatterns[part.slice(1)] ?? "[^/]+"})`;
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    });
+    return new RegExp(`^${parts.join("/")}$`);
+}

package/src/internal.d.ts

@@ -12,3 +12,4 @@ export * from "./pass.ts";
 export * from "./names.ts";
 export * from "./chat.ts";
 export * from "./relay.ts";
+export * from "./doors.ts";

package/src/internal.js

@@ -14,3 +14,4 @@ export * from "./pass.js";
 export * from "./names.js";
 export * from "./chat.js";
 export * from "./relay.js";
+export * from "./doors.js";

package/src/room.d.ts

@@ -1334,6 +1334,70 @@ export interface StateSyncHooks {
 export declare const NO_MESSAGE_TYPE = "(none)";
 export declare const BYTES_MESSAGE_TYPE = "(bytes)";
 export declare const ZAISMA_MESSAGE_TYPE = "(zaisma)";
+/**
+ * Every message a room takes (docs/DOORS.md). receive's switch is over these names, so a new one without a row
+ * doesn't build. A spectator may send only what's for room members. hello comes first and proves the pass; chat is the host's to take before receive (readChatMessage);
+ * bytes is every binary message (receiveBytes). A type with no row, maybe from a newer SDK, is counted and ignored.
+ */
+export declare const ROOM_MESSAGE_DOORS: {
+    readonly hello: {
+        readonly whoMayCall: "pass_holder";
+        readonly reaches: "room";
+        readonly trusts: readonly ["player_pass"];
+        readonly provenBy: {
+            readonly source_path: "packages/game-server/src/pass.ts";
+            readonly symbol_name: "verifyPass";
+        };
+    };
+    readonly probe_answer: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly room: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly kick: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly here: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly idle: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly hidden: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly shown: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly back: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly message: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly bytes: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly chat: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly block: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly unblock: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly friend_request: import("./doors.ts").DoorContractFields & {
+        whoMayCall: import("./doors.ts").DoorCallerProvenByGuard;
+    };
+    readonly "zaisma:purchase": {
+        readonly whoMayCall: "room_player";
+        readonly reaches: "purchase";
+        readonly trusts: readonly ["player_pass", "purchase_receipt"];
+    };
+};
+export type RoomMessageType = keyof typeof ROOM_MESSAGE_DOORS;
 export declare const OTHER_MESSAGE_TYPE = "(other)";
 /** State sync's updates (stateSyncEnabled). */
 export declare const STATE_MESSAGE_TYPE = "(state)";

package/src/room.js

@@ -8,6 +8,7 @@
  */
 import { CHAT_CHECK_LIMITS, CHAT_ROOM_LIMITS } from "./chat.js";
 import { DatabaseError } from "./database.js";
+import { checkDoor } from "./doors.js";
 import { isRoomCode, roomCode } from "./names.js";
 import { readSchedules } from "./schedules.js";
 import { roomCallChecks } from "./room-calls.js";
@@ -502,6 +503,35 @@ export const STATE_SYNC = Symbol("stateSync");
 export const NO_MESSAGE_TYPE = "(none)";
 export const BYTES_MESSAGE_TYPE = "(bytes)";
 export const ZAISMA_MESSAGE_TYPE = "(zaisma)";
+const ROOM_MEMBER = { whoMayCall: "room_member", reaches: "room", trusts: ["player_pass"] };
+const ROOM_PLAYER = { whoMayCall: "room_player", reaches: "room", trusts: ["player_pass"] };
+const ROOM_HOST = { whoMayCall: "room_host", reaches: "room", trusts: ["player_pass"] };
+/**
+ * Every message a room takes (docs/DOORS.md). receive's switch is over these names, so a new one without a row
+ * doesn't build. A spectator may send only what's for room members. hello comes first and proves the pass; chat is the host's to take before receive (readChatMessage);
+ * bytes is every binary message (receiveBytes). A type with no row, maybe from a newer SDK, is counted and ignored.
+ */
+export const ROOM_MESSAGE_DOORS = {
+    hello: { whoMayCall: "pass_holder", reaches: "room", trusts: ["player_pass"], provenBy: { source_path: "packages/game-server/src/pass.ts", symbol_name: "verifyPass" } },
+    probe_answer: ROOM_MEMBER,
+    room: ROOM_HOST,
+    kick: ROOM_HOST,
+    here: ROOM_PLAYER,
+    idle: ROOM_PLAYER,
+    hidden: ROOM_PLAYER,
+    shown: ROOM_PLAYER,
+    back: ROOM_PLAYER,
+    message: ROOM_PLAYER,
+    bytes: ROOM_PLAYER,
+    chat: ROOM_PLAYER,
+    block: ROOM_PLAYER,
+    unblock: ROOM_PLAYER,
+    friend_request: ROOM_PLAYER,
+    "zaisma:purchase": { whoMayCall: "room_player", reaches: "purchase", trusts: ["player_pass", "purchase_receipt"] },
+};
+const isRoomMessageType = (type) => typeof type === "string" && Object.hasOwn(ROOM_MESSAGE_DOORS, type);
+const PLAYER_PROVEN = ["room_member", "room_player"];
+const HOST_PROVEN = ["room_member", "room_player", "room_host"];
 export const OTHER_MESSAGE_TYPE = "(other)";
 /** State sync's updates (stateSyncEnabled). */
 export const STATE_MESSAGE_TYPE = "(state)";
@@ -1759,7 +1789,10 @@ export class RoomCore {
         const presence = this.presence.get(playerId);
         if (presence)
             presence.seenAtMs = this.now();
-        switch (message.type) {
+        const type = isRoomMessageType(message.type) ? message.type : null;
+        if (type && !checkDoor(ROOM_MESSAGE_DOORS[type], this.hostPlayerId === playerId ? HOST_PROVEN : PLAYER_PROVEN))
+            return "not_allowed";
+        switch (type) {
             case "room":
                 return this.hostChange(playerId, message);
             case "kick":
@@ -1838,7 +1871,7 @@ export class RoomCore {
         if (text.length <= ROOM_LIMITS.maximumGameMessageSizeBytes) {
             try {
                 const message = JSON.parse(text);
-                if (message?.type === "probe_answer" && this.answer(spectatorId, message.probeNumber))
+                if (isRoomMessageType(message?.type) && ROOM_MESSAGE_DOORS[message.type].whoMayCall === "room_member" && this.answer(spectatorId, message.probeNumber))
                     return null;
             }
             catch {
@@ -1910,8 +1943,6 @@ export class RoomCore {
      * text between strangers), so the kicked player is told the host removed them.
      */
     hostKick(playerId, message) {
-        if (this.hostPlayerId !== playerId)
-            return "not_allowed";
         const kickedId = message.playerId;
         if (typeof kickedId !== "string" || kickedId === playerId || !this.players.has(kickedId))
             return "bad_message";
@@ -1920,8 +1951,6 @@ export class RoomCore {
     }
     /** The host hides, shows, opens, closes, turns friends' Join on or off, names or labels the room, when the game server allows it. */
     hostChange(playerId, message) {
-        if (this.hostPlayerId !== playerId)
-            return "not_allowed";
         const asked = message.room;
         if (!asked || typeof asked !== "object" || Array.isArray(asked))
             return "bad_message";