@zaisma/game-server 0.0.1 → 1.0.0

package/src/dump.js

@@ -0,0 +1,282 @@
+/**
+ * The game database in and out as SQLite's own SQL dump (docs/DECISIONS.md, "Import, export and undo"):
+ * the CREATE TABLEs and INSERTs that `sqlite3 game.sqlite .dump` writes, so a dump from Zaisma loads into
+ * any SQLite (`sqlite3 game.sqlite < dump.sql`, the Node runner's file) and a dump from there loads into
+ * Zaisma. Zaisma's database is a Durable Object (apps/rooms/src/database.ts); the upload command keeps a
+ * copy of the same reading for .sqlite files (packages/cli/zaisma.mjs), held to this by test/node/dump.test.ts.
+ */
+import { DATABASE_LIMITS, DatabaseError, scanStatements } from "./database.js";
+export const DUMP_LIMITS = {
+    /** The most SQL one part of an export holds, unless a single row is bigger on its own. */
+    exportPartSizeBytes: 4 * 1024 * 1024,
+    /** The most one part of an import may hold: a little over an export's part, so every export part fits. */
+    maximumImportPartSizeBytes: 5 * 1024 * 1024,
+};
+/** A cursor that isn't an earlier part's next_cursor, or whose table is gone. */
+export class DumpCursorError extends Error {
+}
+/** Rows read per SELECT while dumping a table. */
+const PAGE_ROW_COUNT = 500;
+/** A dump starts and ends the way sqlite3's does, so it loads in one transaction anywhere. */
+const DUMP_START = "PRAGMA foreign_keys=OFF;\nBEGIN TRANSACTION;\n";
+const DUMP_END = "COMMIT;\n";
+// What's in the database, in the order it was made: tables, views, indexes and triggers, with what kind
+// of table each is (a normal one, a virtual one, or a virtual table's own "shadow" table) and whether it has
+// rowids. Cloudflare's own tables (_cf_…) are never the developer's.
+const SCHEMA_SQL = "SELECT entry.type AS type, entry.name AS name, entry.tbl_name AS table_name, entry.sql AS sql, listed.type AS table_kind, listed.wr AS is_without_rowid " +
+    "FROM sqlite_schema AS entry LEFT JOIN pragma_table_list AS listed ON listed.schema = 'main' AND listed.name = entry.name " +
+    "WHERE entry.sql IS NOT NULL AND substr(entry.tbl_name, 1, 4) <> '_cf_' ORDER BY entry.rowid";
+/** A name in double quotes, as SQLite takes any table or column name. */
+export function quoteName(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/**
+ * One part of the database's dump, up to partSizeBytes of SQL (more only when one row is bigger on its own),
+ * starting where cursor says, or at the start for null. The parts, put together in order, are one whole dump. It reads
+ * table by table, so a game writing while it runs can land between parts: it isn't a snapshot.
+ */
+export function dumpPart(read, cursor, partSizeBytes = DUMP_LIMITS.exportPartSizeBytes) {
+    let readRowCount = 0;
+    const select = (sql, values = []) => {
+        const answer = read(sql, values);
+        readRowCount += answer.readRowCount;
+        return answer.rows;
+    };
+    const entries = select(SCHEMA_SQL);
+    const tables = entries.filter((entry) => entry.type === "table" && (entry.table_kind === "table" || entry.table_kind === "virtual") && !entry.name.startsWith("sqlite_"));
+    let dumpSql = "";
+    let dumpSizeBytes = 0;
+    let hasRows = false;
+    const add = (sql) => {
+        dumpSql += sql;
+        dumpSizeBytes += utf8SizeBytes(sql);
+    };
+    let tableIndex = 0;
+    let position = null;
+    if (cursor === null)
+        add(DUMP_START);
+    else {
+        position = readCursor(cursor);
+        tableIndex = tables.findIndex((table) => table.name === position.table_name);
+        if (tableIndex === -1)
+            throw new DumpCursorError(`The table ${position.table_name} isn't there any more.`);
+    }
+    for (; tableIndex < tables.length; tableIndex++) {
+        const table = tables[tableIndex];
+        if (!position)
+            add(`${table.sql};\n`);
+        position ??= { table_name: table.name, last_rowid_number: table.is_without_rowid ? null : 0, dumped_row_count: 0 };
+        const columns = select("SELECT name, hidden = 0 AS is_insertable, pk AS primary_key_number FROM pragma_table_xinfo(?) ORDER BY cid", [table.name]);
+        // Generated columns, and a virtual table's hidden ones, can't be inserted: the INSERTs name the rest.
+        const insertedColumns = columns.filter((column) => column.is_insertable === 1);
+        const insertInto = `INSERT INTO ${quoteName(table.name)}${insertedColumns.length < columns.length ? `(${insertedColumns.map((column) => quoteName(column.name)).join(",")})` : ""} VALUES(`;
+        // quote() writes each value as SQL, the way sqlite3's .dump does: 'text' with '' for a quote, X'…' for bytes.
+        const valuesSql = insertedColumns.map((column, i) => `quote(${quoteName(column.name)}) AS value_${i}`).join(", ");
+        const primaryKey = columns.filter((column) => column.primary_key_number > 0).sort((first, second) => first.primary_key_number - second.primary_key_number);
+        while (true) {
+            const rows = position.last_rowid_number === null
+                ? select(`SELECT ${valuesSql} FROM ${quoteName(table.name)} ORDER BY ${primaryKey.map((column) => quoteName(column.name)).join(", ")} LIMIT ${PAGE_ROW_COUNT} OFFSET ?`, [position.dumped_row_count])
+                : select(`SELECT rowid AS paging_rowid, ${valuesSql} FROM ${quoteName(table.name)} WHERE rowid > ? ORDER BY rowid LIMIT ${PAGE_ROW_COUNT}`, [position.last_rowid_number]);
+            for (const row of rows) {
+                const insert = `${insertInto}${insertedColumns.map((_, i) => row[`value_${i}`]).join(",")});\n`;
+                // The part ends before a row that would take it past partSizeBytes; the next starts with that row.
+                if (hasRows && dumpSizeBytes + utf8SizeBytes(insert) > partSizeBytes)
+                    return { dumpSql, nextCursor: writeCursor(position), readRowCount };
+                add(insert);
+                hasRows = true;
+                if (position.last_rowid_number === null)
+                    position.dumped_row_count++;
+                else
+                    position.last_rowid_number = row.paging_rowid;
+            }
+            if (rows.length < PAGE_ROW_COUNT)
+                break;
+        }
+        position = null;
+    }
+    // The rest is small: AUTOINCREMENT's counters, then views, indexes and triggers, made after the rows
+    // so triggers don't fire on them, then the end.
+    if (entries.some((entry) => entry.name === "sqlite_sequence")) {
+        add("DELETE FROM sqlite_sequence;\n");
+        for (const counter of select("SELECT quote(name) AS name_sql, quote(seq) AS counter_sql FROM sqlite_sequence"))
+            add(`INSERT INTO sqlite_sequence VALUES(${counter.name_sql},${counter.counter_sql});\n`);
+    }
+    for (const entry of entries) {
+        if ((entry.type === "view" || entry.type === "index" || entry.type === "trigger") && !entry.table_name.startsWith("sqlite_"))
+            add(`${entry.sql};\n`);
+    }
+    add(DUMP_END);
+    return { dumpSql, nextCursor: null, readRowCount };
+}
+/** How many bytes text takes as UTF-8, without making the bytes. */
+export function utf8SizeBytes(text) {
+    let sizeBytes = 0;
+    for (let i = 0; i < text.length; i++) {
+        const codeUnitNumber = text.charCodeAt(i);
+        // A surrogate pair is one character of 4 bytes, 2 for each half.
+        sizeBytes += codeUnitNumber < 0x80 ? 1 : codeUnitNumber < 0x800 ? 2 : codeUnitNumber >= 0xd800 && codeUnitNumber < 0xe000 ? 2 : 3;
+    }
+    return sizeBytes;
+}
+function writeCursor(position) {
+    const bytes = new TextEncoder().encode(JSON.stringify(position));
+    return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function readCursor(cursor) {
+    let position;
+    try {
+        const binary = atob(cursor.replaceAll("-", "+").replaceAll("_", "/"));
+        position = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0))));
+    }
+    catch {
+        throw new DumpCursorError("The cursor isn't one an export answered.");
+    }
+    const { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount } = (position ?? {});
+    if (typeof tableName !== "string" || !(lastRowidNumber === null || Number.isInteger(lastRowidNumber)) || !Number.isInteger(dumpedRowCount))
+        throw new DumpCursorError("The cursor isn't one an export answered.");
+    return { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount };
+}
+const IMPORT_FIX = "Import takes a dump's CREATE and INSERT statements, as sqlite3's .dump or export_database writes them; it only adds. Run other changes with query_database or batch_database.";
+/**
+ * Reads a part of a dump into the statements to run. Import only adds: it takes CREATE and INSERT
+ * statements, and leaves out what sqlite3 writes around them (the transaction, PRAGMAs, ANALYZE and its
+ * sqlite_stat1 rows). The values in an INSERT become values for ?s, since Zaisma's database takes
+ * statements up to 100 KB and a row of a dump can be bigger; unistr('…'), which sqlite3 writes for text with
+ * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up.
+ */
+export function importStatements(dumpSql) {
+    const statements = [];
+    const scanned = scanStatements(dumpSql);
+    let skippedStatementCount = 0;
+    scanned.forEach((scannedStatement, i) => {
+        const statementNumber = i + 1;
+        const text = dumpSql.slice(scannedStatement.startIndex, scannedStatement.endIndex);
+        const [firstWord = "", secondWord = "", thirdWord = ""] = scannedStatement.leadingWords;
+        const words = scannedStatement.leadingWords.join(" ");
+        const isSkipped = ["BEGIN", "COMMIT", "END", "ROLLBACK", "ANALYZE"].includes(firstWord) ||
+            (firstWord === "PRAGMA" && (secondWord === "FOREIGN_KEYS" || secondWord === "WRITABLE_SCHEMA")) ||
+            /^CREATE TABLE (IF NOT EXISTS )?SQLITE_SEQUENCE$/.test(words) ||
+            words === "DELETE FROM SQLITE_SEQUENCE" ||
+            (firstWord === "INSERT" && secondWord === "INTO" && (thirdWord === "SQLITE_STAT1" || thirdWord === "SQLITE_STAT4"));
+        if (isSkipped) {
+            skippedStatementCount++;
+            return;
+        }
+        const refuse = (message) => new DatabaseError("bad_sql", `Statement ${statementNumber} of the dump (${preview(text)}): ${message}`, IMPORT_FIX);
+        if (firstWord === "CREATE") {
+            statements.push({ sql: text, values: [], statementNumber });
+            return;
+        }
+        if (firstWord !== "INSERT")
+            throw refuse(`${firstWord || "it"} isn't a CREATE or INSERT.`);
+        if (secondWord === "OR" && thirdWord === "REPLACE")
+            throw refuse("INSERT OR REPLACE changes rows that are there.");
+        const bound = bindLiterals(text, refuse);
+        if (thirdWord === "SQLITE_SEQUENCE") {
+            // sqlite_sequence has a row per table and no key: set the counter, never lower it.
+            const counterMatch = /VALUES\s*\(\s*\?\s*,\s*(\d+)\s*\)$/i.exec(bound.sql);
+            if (!counterMatch || bound.values.length !== 1)
+                throw refuse("sqlite_sequence takes a table's name and its counter, like INSERT INTO sqlite_sequence VALUES('scores',12).");
+            const tableName = bound.values[0];
+            const counter = counterMatch[1];
+            // The counter goes in the SQL (it's digits only): bound, a number would be stored as a REAL.
+            statements.push({ sql: `INSERT INTO sqlite_sequence (name, seq) SELECT ?, ${counter} WHERE NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = ?)`, values: [tableName, tableName], statementNumber });
+            statements.push({ sql: `UPDATE sqlite_sequence SET seq = max(seq, ${counter}) WHERE name = ?`, values: [tableName], statementNumber });
+            return;
+        }
+        if (bound.values.length > DATABASE_LIMITS.maximumValueCount)
+            throw new DatabaseError("bad_values", `Statement ${statementNumber} of the dump (${preview(text)}) has ${bound.values.length} text and blob values.`, `Give each row its own INSERT, as sqlite3's .dump does: the database takes up to ${DATABASE_LIMITS.maximumValueCount} values a statement.`);
+        statements.push({ sql: bound.sql, values: bound.values, statementNumber });
+    });
+    return { statements, statementCount: scanned.length, skippedStatementCount };
+}
+/** The start of a statement, for an error. */
+export function preview(text) {
+    const oneLine = text.replace(/\s+/g, " ");
+    return oneLine.length > 80 ? `${oneLine.slice(0, 79)}…` : oneLine;
+}
+/**
+ * An INSERT with its text and blob literals as ?s, and their values: 'it''s' becomes "it's", X'00ff' the
+ * bytes and unistr('a\u000ab') the text it stands for. Numbers, NULL and names stay as they are.
+ */
+function bindLiterals(text, refuse) {
+    const values = [];
+    let sql = "";
+    let i = 0;
+    /** The text of the 'quoted' literal starting at startIndex, and where it ends. */
+    const readQuoted = (startIndex) => {
+        let endIndex = startIndex + 1;
+        let literal = "";
+        while (endIndex < text.length) {
+            if (text[endIndex] === "'") {
+                if (text[endIndex + 1] !== "'")
+                    return { literal, endIndex: endIndex + 1 };
+                literal += "'";
+                endIndex += 2;
+            }
+            else
+                literal += text[endIndex++];
+        }
+        throw refuse("a quote isn't closed.");
+    };
+    const isWordCharacter = (character) => character !== undefined && /[A-Za-z0-9_$]/.test(character);
+    while (i < text.length) {
+        const character = text[i];
+        const afterWord = isWordCharacter(text[i - 1]);
+        if (character === "-" && text[i + 1] === "-") {
+            const endIndex = text.indexOf("\n", i);
+            i = endIndex === -1 ? text.length : endIndex + 1;
+            sql += " ";
+        }
+        else if (character === "/" && text[i + 1] === "*") {
+            const endIndex = text.indexOf("*/", i + 2);
+            i = endIndex === -1 ? text.length : endIndex + 2;
+            sql += " ";
+        }
+        else if (character === '"' || character === "`" || character === "[") {
+            // A name: copied as it is.
+            const close = character === "[" ? "]" : character;
+            let endIndex = i + 1;
+            while (endIndex < text.length && !(text[endIndex] === close && text[endIndex + 1] !== close))
+                endIndex += text[endIndex] === close ? 2 : 1;
+            sql += text.slice(i, endIndex + 1);
+            i = endIndex + 1;
+        }
+        else if (character === "'") {
+            const { literal, endIndex } = readQuoted(i);
+            values.push(literal);
+            sql += "?";
+            i = endIndex;
+        }
+        else if ((character === "x" || character === "X") && text[i + 1] === "'" && !afterWord) {
+            const { literal, endIndex } = readQuoted(i + 1);
+            if (literal.length % 2 || /[^0-9A-Fa-f]/.test(literal))
+                throw refuse(`X'${literal.slice(0, 20)}' isn't bytes in hex.`);
+            values.push(Uint8Array.from({ length: literal.length / 2 }, (_, byteIndex) => parseInt(literal.slice(byteIndex * 2, byteIndex * 2 + 2), 16)));
+            sql += "?";
+            i = endIndex;
+        }
+        else if (!afterWord && /^unistr\s*\(\s*'/i.test(text.slice(i, i + 40))) {
+            const quoteIndex = text.indexOf("'", i);
+            const { literal, endIndex } = readQuoted(quoteIndex);
+            const closeMatch = /^\s*\)/.exec(text.slice(endIndex));
+            if (!closeMatch)
+                throw refuse("unistr( takes one 'text'.");
+            values.push(literal.replace(/\\(\\|u[0-9A-Fa-f]{4}|\+[0-9A-Fa-f]{6}|U[0-9A-Fa-f]{8}|[0-9A-Fa-f]{4})/g, (_, escape) => (escape === "\\" ? "\\" : String.fromCodePoint(parseInt(escape.replace(/^[uU+]/, ""), 16)))));
+            sql += "?";
+            i = endIndex + closeMatch[0].length;
+        }
+        else if (isWordCharacter(character)) {
+            let endIndex = i + 1;
+            while (isWordCharacter(text[endIndex]))
+                endIndex++;
+            sql += text.slice(i, endIndex);
+            i = endIndex;
+        }
+        else {
+            sql += character;
+            i++;
+        }
+    }
+    return { sql, values };
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, type Audience, type AwayInfo, type AwayMode, type AwayReason, type BroadcastOptions, type Delivery, type GameServer, type GameServerErrorCode, type HandlerResult, type IdleCheck, type JoinAnswer, type JoinInfo, type KickOptions, type LeaveInfo, type LeaveReason, type MoveOptions, type MoveResult, type Player, type Refusal, type ReserveOptions, type RestoreInfo, type Room, type RoomErrorCode, type RoomInfo, type SendOptions, type VersionUpdate, } from "./room.ts";
+export { REQUEST_LIMITS, type RequestErrorCode, type Server } from "./requests.ts";
+export { SCHEDULE_LIMITS, type Schedule, type ScheduledRun } from "./schedules.ts";
+export { WEBHOOK_LIMITS, verifyWebhook, type WebhookError, type WebhookErrorCode, type WebhookEvent, type WebhookEventKind, type WebhookHeaders } from "./webhooks.ts";
+export { DATABASE_LIMITS, DatabaseError, type DatabaseErrorCode, type DatabaseRow, type DatabaseStatement, type DatabaseValue, type GameDatabase } from "./database.ts";
+export { OUTSIDE_CALL_LIMITS, OutsideCallError, type OutsideCallErrorCode } from "./outside-calls.ts";
+export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt, type PassClaims, type PassErrorCode, type PassExpectations, type PlayerKind, type PublicKey, type ReceiptClaims, type ReceiptErrorCode, type ReceiptExpectations, type WhoCanChat } from "./pass.ts";
+export { CHAT_CHECK_LIMITS, ChatCheckError, checkChat, type ChatCheck, type ChatCheckOptions, type ChatCheckReason } from "./chat.ts";
+export { guestName, isRoomCode } from "./names.ts";
+export { relay } from "./relay.ts";

package/src/index.js

@@ -0,0 +1,12 @@
+// What @zaisma/game-server gives developers, named one by one: from v1 it only grows (test/contracts).
+// Zaisma's own parts of the package, never locked, are in ./internal.
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, } from "./room.js";
+export { REQUEST_LIMITS } from "./requests.js";
+export { SCHEDULE_LIMITS } from "./schedules.js";
+export { WEBHOOK_LIMITS, verifyWebhook } from "./webhooks.js";
+export { DATABASE_LIMITS, DatabaseError } from "./database.js";
+export { OUTSIDE_CALL_LIMITS, OutsideCallError } from "./outside-calls.js";
+export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt } from "./pass.js";
+export { CHAT_CHECK_LIMITS, ChatCheckError, checkChat } from "./chat.js";
+export { guestName, isRoomCode } from "./names.js";
+export { relay } from "./relay.js";

package/src/internal.d.ts

@@ -0,0 +1,13 @@
+export * from "./room.ts";
+export * from "./room-calls.ts";
+export * from "./state-sync.ts";
+export * from "./database.ts";
+export * from "./dump.ts";
+export * from "./requests.ts";
+export * from "./outside-calls.ts";
+export * from "./schedules.ts";
+export * from "./webhooks.ts";
+export * from "./pass.ts";
+export * from "./names.ts";
+export * from "./chat.ts";
+export * from "./relay.ts";

package/src/internal.js

@@ -0,0 +1,15 @@
+// Zaisma's own use of the game server package: everything in src, and what only Zaisma does (signing passes).
+// Never published or locked: games and developers' servers use the package's index.
+export * from "./room.js";
+export * from "./room-calls.js";
+export * from "./state-sync.js";
+export * from "./database.js";
+export * from "./dump.js";
+export * from "./requests.js";
+export * from "./outside-calls.js";
+export * from "./schedules.js";
+export * from "./webhooks.js";
+export * from "./pass.js";
+export * from "./names.js";
+export * from "./chat.js";
+export * from "./relay.js";

package/src/names.d.ts

@@ -0,0 +1,4 @@
+/** A friendly guest name like "Swift Fox 42". Guests can't type their own names. */
+export declare function guestName(): string;
+export declare function roomCode(): string;
+export declare function isRoomCode(code: string): boolean;

package/src/names.js

@@ -0,0 +1,18 @@
+const ADJECTIVES = ["Swift", "Brave", "Quiet", "Lucky", "Bright", "Clever", "Sunny", "Bold", "Calm", "Fuzzy", "Jolly", "Nimble", "Rapid", "Sly", "Witty", "Zany", "Cosmic", "Mighty", "Tiny", "Wild"];
+const ANIMALS = ["Fox", "Otter", "Panda", "Hawk", "Lynx", "Koala", "Badger", "Falcon", "Gecko", "Moose", "Owl", "Raven", "Seal", "Tiger", "Wolf", "Yak", "Bison", "Crane", "Heron", "Newt"];
+function pick(list, randomNumber) {
+    return list[randomNumber % list.length];
+}
+/** A friendly guest name like "Swift Fox 42". Guests can't type their own names. */
+export function guestName() {
+    const [adjectiveNumber, animalNumber, endNumber] = crypto.getRandomValues(new Uint32Array(3));
+    return `${pick(ADJECTIVES, adjectiveNumber)} ${pick(ANIMALS, animalNumber)} ${10 + (endNumber % 90)}`;
+}
+/** No 0/O or 1/I, so codes read out loud or typed from a screen don't get mixed up. */
+const CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
+export function roomCode() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(6)), (byte) => CODE_ALPHABET[byte & 31]).join("");
+}
+export function isRoomCode(code) {
+    return /^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{6}$/.test(code);
+}

package/src/outside-calls.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Calls from a game server to other servers (game server reach): plain fetch(). On Zaisma every call
+ * goes through the rooms Worker's gateway (apps/rooms/src/outbound.ts), which takes only https to the
+ * hosts the game lists in game_server_allowed_hosts; a call it refuses throws an OutsideCallError in
+ * the game server with one of these codes. On the developer's own server the Node runner calls out
+ * freely, so the same code runs in both.
+ */
+export type OutsideCallErrorCode = 
+/** Only https: addresses. */
+"not_https"
+/** An IP address, this computer, or Zaisma's own domains. */
+ | "unreachable_host"
+/** A host the game doesn't list in game_server_allowed_hosts. */
+ | "host_not_allowed"
+/** More calls a minute than a game makes in one place (OUTSIDE_CALL_LIMITS.maximumCallsPerMin). */
+ | "outside_call_limit"
+/** A body over OUTSIDE_CALL_LIMITS.maximumBodySizeBytes. */
+ | "too_big"
+/** No answer within OUTSIDE_CALL_LIMITS.timeoutSec. */
+ | "outside_call_timeout"
+/** The other server couldn't be reached, like a name that doesn't exist. */
+ | "outside_call_failed";
+export declare const OUTSIDE_CALL_LIMITS: {
+    readonly maximumBodySizeBytes: number;
+    readonly timeoutSec: 10;
+    readonly maximumCallsPerMin: 600;
+};
+export declare const OUTSIDE_CALL_ERROR_CODES: readonly string[];
+/** A call from a game server to another server that Zaisma's gateway refused (or that failed), with a code, what happened and what to do. */
+export declare class OutsideCallError extends Error {
+    readonly code: OutsideCallErrorCode;
+    readonly fix: string;
+    constructor(code: OutsideCallErrorCode, message: string, fix: string);
+    /** True for any error named OutsideCallError with a known code, so instanceof works for the copy a game's sandbox has too. */
+    static [Symbol.hasInstance](candidate: unknown): boolean;
+}
+/** What a refused call answers inside the sandbox, which its fetch() turns into an OutsideCallError. */
+export interface OutsideCallRefusal {
+    error: {
+        code: OutsideCallErrorCode;
+        message: string;
+        fix: string;
+    };
+}
+/** The header a refusal comes back with, so the sandbox can tell it from a server's own answer. */
+export declare const OUTSIDE_CALL_REFUSAL_HEADER = "zaisma-outside-call-refused";

package/src/outside-calls.js

@@ -0,0 +1,30 @@
+/**
+ * Calls from a game server to other servers (game server reach): plain fetch(). On Zaisma every call
+ * goes through the rooms Worker's gateway (apps/rooms/src/outbound.ts), which takes only https to the
+ * hosts the game lists in game_server_allowed_hosts; a call it refuses throws an OutsideCallError in
+ * the game server with one of these codes. On the developer's own server the Node runner calls out
+ * freely, so the same code runs in both.
+ */
+export const OUTSIDE_CALL_LIMITS = {
+    maximumBodySizeBytes: 5 * 1024 * 1024,
+    timeoutSec: 10,
+    maximumCallsPerMin: 600,
+};
+export const OUTSIDE_CALL_ERROR_CODES = ["not_https", "unreachable_host", "host_not_allowed", "outside_call_limit", "too_big", "outside_call_timeout", "outside_call_failed"];
+/** A call from a game server to another server that Zaisma's gateway refused (or that failed), with a code, what happened and what to do. */
+export class OutsideCallError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(`${message} ${fix} (${code})`);
+        this.name = "OutsideCallError";
+        this.code = code;
+        this.fix = fix;
+    }
+    /** True for any error named OutsideCallError with a known code, so instanceof works for the copy a game's sandbox has too. */
+    static [Symbol.hasInstance](candidate) {
+        return candidate instanceof Error && candidate.name === "OutsideCallError" && OUTSIDE_CALL_ERROR_CODES.includes(candidate.code);
+    }
+}
+/** The header a refusal comes back with, so the sandbox can tell it from a server's own answer. */
+export const OUTSIDE_CALL_REFUSAL_HEADER = "zaisma-outside-call-refused";

package/src/pass.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Player passes: standard JWTs signed with Ed25519 (EdDSA). Our rooms check them,
+ * and so can any developer's own server, using the keys published at
+ * /.well-known/jwks.json. Any JWT library that supports EdDSA works.
+ */
+/**
+ * What a pass proves: who the player is, for which game, until when. Nothing more; anything else
+ * about an account (its name) comes from its public profile, <issuer>/v1/players/<id>. A game that
+ * needs accounts gives guests no pass at all. Fields can be added within v1; none is removed.
+ */
+export interface PassClaims {
+    /** Player ID. An account's is the same in every game; a guest's is random and only valid for this pass. */
+    sub: string;
+    /** A guest's generated name. Account passes carry none. */
+    name?: string;
+    /** The game's slug: a pass only works for the game it was issued for. */
+    aud: string;
+    /** Who made it: https://rooms.zaisma.com (PASS_ISSUER_URL) on zaisma.com. */
+    iss: string;
+    /** The pass contract it follows: 1. verifyPass refuses a number it doesn't know (wrong_version). */
+    pass_version_number: number;
+    /** guest or account, or a kind added later: treat one your server doesn't know as a guest. */
+    kind: PlayerKind | (string & {});
+    /**
+     * Who an account lets chat with it: nobody, its friends, or anyone in its chat group, or a choice
+     * added later (canChat matches only the ones it knows, so an unknown one chats with nobody).
+     * Guests' passes have none: guests don't chat.
+     */
+    who_can_chat?: WhoCanChat | (string & {});
+    /**
+     * For accounts that chat with anyone, the group they can chat in (chat_group_…): two such players
+     * chat when their groups match (canChat). Opaque and different in every game, so it never says an
+     * age; a game could guess which group is the younger one from its size.
+     */
+    chat_group_id?: string;
+    /**
+     * An account's own player tag in this game (player_tag_…): opaque, and different in every game, so
+     * it says nothing outside it. Other passes list it to say they're friends (friend_player_tag_ids) or
+     * have a block (block_player_tag_ids). Guests' passes have none.
+     */
+    player_tag_id?: string;
+    /**
+     * The player tags of an account's friends, up to 200, as they were when the pass was made: never
+     * their player IDs, so a game learns only which of its own players are friends, by their passes
+     * (passesAreFriends). Friends are always two-way, so passesAreFriends asks both passes. Guests'
+     * passes have none.
+     */
+    friend_player_tag_ids?: string[];
+    /**
+     * The player tags of the accounts this one has a block with, either way, newest first and up to 100,
+     * as they were when the pass was made. Never says who made a block, and means nothing without the
+     * other player's pass: two players have a block between them when either pass lists the other's
+     * player_tag_id (passesHaveBlockBetween).
+     */
+    block_player_tag_ids?: string[];
+    /**
+     * The permanent items an account owns in this game (bought or granted, not refunded), by item_name, as
+     * they were when the pass was made: [] for guests and when the player owns nothing here. Consumables are
+     * never listed: they're delivered once and then they're the game's to count.
+     */
+    owned_item_names: string[];
+    iat: number;
+    exp: number;
+}
+/** A signed-in Zaisma account, or a guest. */
+export type PlayerKind = "guest" | "account";
+/** No chat, friends only, or anyone in the same chat group: the player's "Who can chat with you" setting (docs/DECISIONS.md, "Social settings, with the social modes as presets"). */
+export type WhoCanChat = "nobody" | "friends" | "anyone";
+/** A pass's JWS header typ (RFC 8725 explicit typing): verifyPass refuses any other token (wrong_kind). */
+export declare const PASS_TOKEN_TYPE = "pass+jwt";
+/** The pass contract this copy reads: verifyPass refuses any other pass_version_number (wrong_version). */
+export declare const PASS_VERSION_NUMBER = 1;
+/** Zaisma's pass issuer: verifyPass expects it unless told another (a local preview of Zaisma). */
+export declare const PASS_ISSUER_URL = "https://rooms.zaisma.com";
+/**
+ * Whether two players have a block between them, by the passes your server checked (verifyPass): either
+ * one blocked the other, which neither pass says. A block is a wall both ways: deliver nothing from one
+ * to the other (chat, voice, emotes) and don't match them together when you can help it, but never keep
+ * either out of a room. A new block reaches your server with the blocker's next pass, and the blocker's
+ * game also tells the room ({ type: "block", playerId }), which room.hasBlockBetween covers.
+ */
+export declare function passesHaveBlockBetween(first: PassClaims, second: PassClaims): boolean;
+/**
+ * Whether two players are Zaisma friends, by the passes your server checked (verifyPass): both accounts,
+ * each pass listing the other's player_tag_id, so removing a friend holds as soon as either side has a
+ * new pass. It works across rooms too: any two passes for the game. Use it for friends-only chat (canChat
+ * does), parties, or showing a player their friends; guests are never anyone's friend.
+ */
+export declare function passesAreFriends(first: PassClaims, second: PassClaims): boolean;
+/**
+ * Whether two players may chat, by the passes your server checked (verifyPass): both accounts, no block
+ * between them, neither letting nobody chat, and either friends or both letting anyone chat, in the same
+ * chat group. Guests and accounts set to nobody never chat; accounts set to friends chat only with
+ * friends (passesAreFriends). Use it on every message your own server delivers, text or voice; Zaisma's
+ * chat check (checkChat) applies the same rule, and Zaisma rooms will do the same for you.
+ */
+export declare function canChat(first: PassClaims, second: PassClaims): boolean;
+export type PublicKey = JsonWebKey & {
+    kid: string;
+};
+/** Why verifyPass refused a pass. wrong_kind: a receipt, or another token. wrong_version: a pass_version_number this copy doesn't know. */
+export type PassErrorCode = "malformed" | "unknown_key" | "bad_signature" | "expired" | "wrong_game" | "wrong_issuer" | "wrong_kind" | "wrong_version";
+export declare class PassError extends Error {
+    readonly code: PassErrorCode;
+    constructor(code: PassErrorCode);
+}
+/** Why verifyReceipt refused a receipt. wrong_kind: it's a pass, or another token. wrong_version: a receipt_version_number this copy doesn't know. */
+export type ReceiptErrorCode = "malformed" | "unknown_key" | "bad_signature" | "expired" | "wrong_game" | "wrong_issuer" | "wrong_kind" | "wrong_version";
+export declare class ReceiptError extends Error {
+    readonly code: ReceiptErrorCode;
+    constructor(code: ReceiptErrorCode);
+}
+/** A receipt's JWS header typ (RFC 8725 explicit typing): verifyReceipt refuses any other token (wrong_kind). */
+export declare const RECEIPT_TOKEN_TYPE = "receipt+jwt";
+/** Who signs receipts on zaisma.com: a receipt's iss, apart from a pass's (PASS_ISSUER_URL). */
+export declare const RECEIPT_ISSUER_URL = "https://rooms.zaisma.com/receipts";
+/** The receipt contract this copy reads: verifyReceipt refuses any other receipt_version_number (wrong_version). */
+export declare const RECEIPT_VERSION_NUMBER = 1;
+/** Make a new signing key, as a JWK string for a signing secret (the rooms Worker's PASS_SIGNING_KEY and RECEIPT_SIGNING_KEY). */
+export declare function generateSigningKey(): Promise<string>;
+export interface SigningKey {
+    key: CryptoKey;
+    publicKey: PublicKey;
+}
+export declare function loadSigningKey(secret: string): Promise<SigningKey>;
+/** A pass to sign: Zaisma always lists owned_item_names, and verifyPass reads a pass without them as owning nothing. */
+export declare function signPass(signing: SigningKey, claims: Omit<PassClaims, "owned_item_names"> & {
+    owned_item_names?: string[];
+}): Promise<string>;
+export declare function jwks(keys: PublicKey[]): {
+    keys: PublicKey[];
+};
+/** What verifyPass checks a pass against: the game it's for, and who made it (PASS_ISSUER_URL unless a local preview of Zaisma). */
+export interface PassExpectations {
+    gameSlug: string;
+    issuerUrl?: string;
+    /** The time to check exp against, in epoch milliseconds: now unless a test says otherwise. */
+    nowMs?: number;
+}
+/** Check a pass. Throws PassError if it's forged, expired, for another game, not a pass, or a version this copy doesn't know. */
+export declare function verifyPass(token: string, keys: PublicKey[], expect: PassExpectations): Promise<PassClaims>;
+/**
+ * What a receipt proves: that this player bought or was granted this item in this game, and the purchase's
+ * status when the receipt was signed. Signed with Zaisma's receipt key, published for good at its own address
+ * (/.well-known/receipt-jwks.json), apart from the pass key, so a receipt never expires and a receipt key never
+ * signs a pass anyone takes. Its typ is receipt+jwt and its issuer
+ * <pass issuer>/receipts (https://rooms.zaisma.com/receipts), so no JWT library takes it for a pass.
+ *
+ * Deliver once per purchase_id, and only when purchase_status is completed; never compare receipt strings,
+ * since the same purchase signs again with a new iat. item_kind, purchase_source and purchase_status may gain
+ * values within v1: a value your server doesn't know means don't deliver.
+ */
+export interface ReceiptClaims {
+    /** The player's ID. */
+    sub: string;
+    /** The game's slug: a receipt is for the game it was issued for. */
+    aud: string;
+    /** https://rooms.zaisma.com/receipts on zaisma.com: the pass issuer with /receipts. */
+    iss: string;
+    /** The purchase's ID, as purchase_id, for JWT tools. */
+    jti: string;
+    /** The receipt contract it follows: 1. verifyReceipt refuses a number it doesn't know. */
+    receipt_version_number: number;
+    /** The purchase's ID (purchase_…): one purchase, one delivery. */
+    purchase_id: string;
+    /** When it was bought or granted, as an ISO date. */
+    purchased_at: string;
+    /** completed, refunded or charged_back when it was signed; deliver only on completed. */
+    purchase_status: "completed" | "refunded" | "charged_back" | (string & {});
+    item_name: string;
+    item_kind: "permanent" | "consumable" | (string & {});
+    /** How many of the item: 1 for a permanent item. */
+    item_count: number;
+    /** sale: paid through the buy sheet. grant: the developer gave it, with no money. */
+    purchase_source: "sale" | "grant" | (string & {});
+    /** What the whole purchase paid, in the currency's minor units; null for a grant. */
+    paid_minor_units: number | null;
+    currency_code: string | null;
+    /** The game's own ID for the player's account in its own system, as the game gave it; null when it gave none. */
+    game_account_id: string | null;
+    /** When the receipt was signed, in epoch seconds (not when it was bought: that's purchased_at). */
+    iat: number;
+    /** No receipt expires today; verifyReceipt refuses one past its exp if one ever does. */
+    exp?: number;
+}
+/** What verifyReceipt checks a receipt against: the game it's for, and who made it (RECEIPT_ISSUER_URL unless a local preview of Zaisma). */
+export interface ReceiptExpectations {
+    gameSlug: string;
+    issuerUrl?: string;
+    /** The time to check exp against, in epoch milliseconds: now unless a test says otherwise. */
+    nowMs?: number;
+}
+/** Check a receipt. Throws ReceiptError if it's forged, for another game, a pass (wrong_kind), past its exp, or a version this copy doesn't know. */
+export declare function verifyReceipt(token: string, keys: PublicKey[], expect: ReceiptExpectations): Promise<ReceiptClaims>;