@zaisma/game-server 0.0.1 → 1.1.0

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>;

package/src/pass.js

@@ -0,0 +1,231 @@
+/**
+ * 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.
+ */
+/** A pass's JWS header typ (RFC 8725 explicit typing): verifyPass refuses any other token (wrong_kind). */
+export const PASS_TOKEN_TYPE = "pass+jwt";
+/** The pass contract this copy reads: verifyPass refuses any other pass_version_number (wrong_version). */
+export const PASS_VERSION_NUMBER = 1;
+/** Zaisma's pass issuer: verifyPass expects it unless told another (a local preview of Zaisma). */
+export const PASS_ISSUER_URL = "https://rooms.zaisma.com";
+/** The pass helpers take passes verifyPass checked: anything else is a mistake in the server's code, not a player's. */
+function mustBePasses(first, second, helper) {
+    for (const pass of [first, second]) {
+        if (!pass || typeof pass !== "object" || typeof pass.sub !== "string")
+            throw new TypeError(`${helper} takes two passes' claims, as verifyPass answered them.`);
+    }
+}
+/**
+ * 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 function passesHaveBlockBetween(first, second) {
+    mustBePasses(first, second, "passesHaveBlockBetween");
+    if (first.sub === second.sub)
+        return false;
+    const lists = (pass, other) => typeof other.player_tag_id === "string" && Array.isArray(pass.block_player_tag_ids) && pass.block_player_tag_ids.includes(other.player_tag_id);
+    return lists(first, second) || lists(second, first);
+}
+/**
+ * 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 function passesAreFriends(first, second) {
+    mustBePasses(first, second, "passesAreFriends");
+    if (first.kind !== "account" || second.kind !== "account" || first.sub === second.sub)
+        return false;
+    const lists = (pass, other) => typeof other.player_tag_id === "string" && Array.isArray(pass.friend_player_tag_ids) && pass.friend_player_tag_ids.includes(other.player_tag_id);
+    return lists(first, second) && lists(second, first);
+}
+/**
+ * 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 function canChat(first, second) {
+    mustBePasses(first, second, "canChat");
+    if (first.kind !== "account" || second.kind !== "account" || first.sub === second.sub)
+        return false;
+    if (passesHaveBlockBetween(first, second))
+        return false;
+    const isOpenTo = (whoCanChat) => whoCanChat === "friends" || whoCanChat === "anyone";
+    if (!isOpenTo(first.who_can_chat) || !isOpenTo(second.who_can_chat))
+        return false;
+    if (passesAreFriends(first, second))
+        return true;
+    return first.who_can_chat === "anyone" && second.who_can_chat === "anyone" && typeof first.chat_group_id === "string" && first.chat_group_id === second.chat_group_id;
+}
+// Plain class fields (no TypeScript-only syntax) so Node can run this file directly.
+export class PassError extends Error {
+    code;
+    constructor(code) {
+        super(`Player pass rejected: ${code}`);
+        this.code = code;
+    }
+}
+export class ReceiptError extends Error {
+    code;
+    constructor(code) {
+        super(`Receipt rejected: ${code}`);
+        this.name = "ReceiptError";
+        this.code = code;
+    }
+}
+/** A receipt's JWS header typ (RFC 8725 explicit typing): verifyReceipt refuses any other token (wrong_kind). */
+export 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 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 const RECEIPT_VERSION_NUMBER = 1;
+const ED25519 = { name: "Ed25519" };
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+    const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+async function keyId(publicKeyBase64Url) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(publicKeyBase64Url)));
+    return toBase64Url(digest).slice(0, 16);
+}
+/** 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 async function generateSigningKey() {
+    const pair = (await crypto.subtle.generateKey(ED25519, true, ["sign", "verify"]));
+    const jwk = (await crypto.subtle.exportKey("jwk", pair.privateKey));
+    return JSON.stringify({ kty: jwk.kty, crv: jwk.crv, x: jwk.x, d: jwk.d });
+}
+export async function loadSigningKey(secret) {
+    const jwk = JSON.parse(secret);
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x || !jwk.d)
+        throw new Error("A signing key must be an Ed25519 private JWK");
+    const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x, d: jwk.d }, ED25519, false, ["sign"]);
+    const publicKey = { kty: "OKP", crv: "Ed25519", x: jwk.x, kid: await keyId(jwk.x), alg: "EdDSA", use: "sig" };
+    return { key, publicKey };
+}
+/** A pass to sign: Zaisma always lists owned_item_names, and verifyPass reads a pass without them as owning nothing. */
+export async function signPass(signing, claims) {
+    const header = toBase64Url(encoder.encode(JSON.stringify({ alg: "EdDSA", typ: PASS_TOKEN_TYPE, kid: signing.publicKey.kid })));
+    const body = toBase64Url(encoder.encode(JSON.stringify(claims)));
+    const signature = new Uint8Array(await crypto.subtle.sign(ED25519, signing.key, encoder.encode(`${header}.${body}`)));
+    return `${header}.${body}.${toBase64Url(signature)}`;
+}
+export function jwks(keys) {
+    return { keys };
+}
+/**
+ * A token's claims once its signature checks out against one of the keys, for verifyPass and verifyReceipt, which
+ * say how to refuse. isKind checks the header's typ before any key is looked up, so a token of the other kind is
+ * wrong_kind wherever it's checked, whichever keys are at hand; it only ever refuses, so an unsigned header is enough.
+ */
+async function signedToken(token, keys, isKind, refuse) {
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3)
+        throw refuse("malformed");
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(decoder.decode(fromBase64Url(parts[0])));
+        claims = JSON.parse(decoder.decode(fromBase64Url(parts[1])));
+    }
+    catch {
+        throw refuse("malformed");
+    }
+    if (!header || header.alg !== "EdDSA" || !claims || typeof claims !== "object")
+        throw refuse("malformed");
+    if (!isKind(header.typ))
+        throw refuse("wrong_kind");
+    const jwk = keys.find((publicKey) => publicKey.kid === header.kid);
+    if (!jwk)
+        throw refuse("unknown_key");
+    const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
+    let signature;
+    try {
+        signature = fromBase64Url(parts[2]);
+    }
+    catch {
+        throw refuse("malformed");
+    }
+    if (!(await crypto.subtle.verify(ED25519, key, signature, encoder.encode(`${parts[0]}.${parts[1]}`))))
+        throw refuse("bad_signature");
+    return { claims };
+}
+const isStringList = (given) => Array.isArray(given) && given.every((entry) => typeof entry === "string");
+/** 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 async function verifyPass(token, keys, expect) {
+    // A receipt, or any other token, never stands in for a pass, whichever keys it's checked against.
+    const { claims: signed } = await signedToken(token, keys, (typ) => typ === PASS_TOKEN_TYPE, (code) => new PassError(code));
+    const claims = signed;
+    if (claims.pass_version_number !== PASS_VERSION_NUMBER)
+        throw new PassError("wrong_version");
+    const nowSec = Math.floor((expect.nowMs ?? Date.now()) / 1000);
+    if (typeof claims.exp !== "number" || claims.exp <= nowSec)
+        throw new PassError("expired");
+    if (claims.iss !== (expect.issuerUrl ?? PASS_ISSUER_URL))
+        throw new PassError("wrong_issuer");
+    if (claims.aud !== expect.gameSlug)
+        throw new PassError("wrong_game");
+    if (typeof claims.sub !== "string" || typeof claims.kind !== "string")
+        throw new PassError("malformed");
+    if (claims.kind === "guest" && typeof claims.name !== "string")
+        throw new PassError("malformed");
+    if (claims.who_can_chat !== undefined && typeof claims.who_can_chat !== "string")
+        throw new PassError("malformed");
+    if (claims.chat_group_id !== undefined && typeof claims.chat_group_id !== "string")
+        throw new PassError("malformed");
+    if (claims.player_tag_id !== undefined && typeof claims.player_tag_id !== "string")
+        throw new PassError("malformed");
+    if (claims.friend_player_tag_ids !== undefined && !isStringList(claims.friend_player_tag_ids))
+        throw new PassError("malformed");
+    if (claims.block_player_tag_ids !== undefined && !isStringList(claims.block_player_tag_ids))
+        throw new PassError("malformed");
+    if (claims.owned_item_names === undefined)
+        claims.owned_item_names = [];
+    if (!isStringList(claims.owned_item_names))
+        throw new PassError("malformed");
+    return claims;
+}
+/** 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 async function verifyReceipt(token, keys, expect) {
+    const { claims: signed } = await signedToken(token, keys, (typ) => typ === RECEIPT_TOKEN_TYPE, (code) => new ReceiptError(code));
+    const claims = signed;
+    if (claims.receipt_version_number !== RECEIPT_VERSION_NUMBER)
+        throw new ReceiptError(Number.isInteger(claims.receipt_version_number) ? "wrong_version" : "malformed");
+    if (claims.exp !== undefined && (typeof claims.exp !== "number" || claims.exp <= Math.floor((expect.nowMs ?? Date.now()) / 1000)))
+        throw new ReceiptError("expired");
+    if (claims.iss !== (expect.issuerUrl ?? RECEIPT_ISSUER_URL))
+        throw new ReceiptError("wrong_issuer");
+    if (claims.aud !== expect.gameSlug)
+        throw new ReceiptError("wrong_game");
+    const isText = (given) => typeof given === "string" && given.length > 0;
+    const isNullOr = (given, type) => given === null || typeof given === type;
+    if (!isText(claims.sub) ||
+        !isText(claims.jti) ||
+        !isText(claims.purchase_id) ||
+        !isText(claims.purchased_at) ||
+        !isText(claims.purchase_status) ||
+        !isText(claims.item_name) ||
+        !isText(claims.item_kind) ||
+        !Number.isInteger(claims.item_count) ||
+        !isText(claims.purchase_source) ||
+        !isNullOr(claims.paid_minor_units, "number") ||
+        !isNullOr(claims.currency_code, "string") ||
+        !isNullOr(claims.game_account_id, "string") ||
+        typeof claims.iat !== "number") {
+        throw new ReceiptError("malformed");
+    }
+    return claims;
+}

package/src/relay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The built-in game server for games without server code: passes each message and bytes on to
+ * everyone else as they were sent, with fromPlayerId saying whose they are. With no server code to decide, the
+ * room's first player may hide, show, open and close it, and each player's game sets its own idle check
+ * (joinRoom({ idleTimeoutSec, idleCheckEnabled })).
+ */
+export declare const relay: import("./room.ts").GameServer<{}>;

package/src/relay.js

@@ -0,0 +1,20 @@
+import { defineGameServer } from "./room.js";
+/**
+ * The built-in game server for games without server code: passes each message and bytes on to
+ * everyone else as they were sent, with fromPlayerId saying whose they are. With no server code to decide, the
+ * room's first player may hide, show, open and close it, and each player's game sets its own idle check
+ * (joinRoom({ idleTimeoutSec, idleCheckEnabled })).
+ */
+export const relay = defineGameServer({
+    // Not the rooms' 100: the relay sends every message to everyone, so a room's sends grow with the square of its players.
+    maximumPlayerCount: 16,
+    hostControlsEnabled: true,
+    idleCheck: "client",
+    setup: () => ({}),
+    onMessage(state, player, room, message) {
+        room.broadcast(message, { exceptPlayerId: player.id, fromPlayerId: player.id });
+    },
+    onBytes(state, player, room, bytes) {
+        room.broadcastBytes(bytes, { exceptPlayerId: player.id, fromPlayerId: player.id });
+    },
+});

package/src/requests.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Requests: plain calls from a game to its game server's onRequest, outside any room, for a
+ * leaderboard, a shop or a daily reward in any game, single-player ones too. Zaisma rooms answer them
+ * at rooms.zaisma.com (apps/rooms/src/game-server.ts) and the Node runner on the developer's own
+ * server (@zaisma/game-server/node), both at POST /v1/requests/<game>, both checked here so a request that works
+ * in one works the same in the other.
+ *
+ * The game sends { pass, request } as text/plain JSON (so the browser needs no preflight): its player
+ * pass, so onRequest knows who's asking, and its request, plain JSON. It gets back { answer }, what
+ * onRequest answered, or { error: { code, message } }.
+ */
+import type { GameDatabase } from "./database.ts";
+import type { ReceiptClaims } from "./pass.ts";
+import type { Player } from "./room.ts";
+/**
+ * What onRequest, onSchedule and onWebhook reach besides what they're given: the game's own database, the
+ * same one its rooms use, its secrets, and receipt checks.
+ */
+export interface Server {
+    database: GameDatabase;
+    /**
+     * The game's secrets, by name, like server.secrets.DISCORD_WEBHOOK_URL: set per game on Zaisma
+     * (set_secret) and never shown again, or the environment variables on your own server.
+     */
+    secrets: Readonly<Record<string, string>>;
+    /** Check a purchase's receipt, as room.verifyReceipt does: the runtime fills in Zaisma's keys and this game. */
+    verifyReceipt(receipt: string): Promise<ReceiptClaims>;
+}
+export declare const REQUEST_LIMITS: {
+    /** A request, as JSON. */
+    readonly maximumRequestSizeBytes: number;
+    /**
+     * The player pass that comes with it, or with a room's hello: the fullest pass Zaisma makes (1,000 owned
+     * items with 40-character names, 200 friends and 100 blocks) is about 70 KB, with room to spare.
+     */
+    readonly maximumPassSizeBytes: number;
+    /** What onRequest answers, as JSON. */
+    readonly maximumAnswerSizeBytes: number;
+    /** How long onRequest may take, awaiting the database included, before the request fails. */
+    readonly answerTimeoutSec: 10;
+};
+export type RequestErrorCode = "bad_request" | "too_big" | "bad_pass" | "account_needed" | "game_not_open_to_player" | "game_unavailable" | "no_request_handler" | "game_server_error" | "hosting_paused" | "slow_down" | "bad_origin" | "busy";
+export declare const REQUEST_ERROR_TEXT: Record<RequestErrorCode, string>;
+/** The HTTP status each request error answers with. */
+export declare const REQUEST_ERROR_HTTP_STATUS: Record<RequestErrorCode, number>;
+/** The body of an error answer. message replaces the usual text. */
+export declare function requestError(code: RequestErrorCode, message?: string): {
+    error: {
+        code: RequestErrorCode;
+        message: string;
+    };
+};
+/**
+ * Read what a game sent: its pass and its request, plain JSON within REQUEST_LIMITS.maximumRequestSizeBytes
+ * (nothing is null). The pass's own size doesn't count.
+ */
+export declare function readRequestBody(text: string): {
+    pass: string;
+    request: unknown;
+} | {
+    code: "bad_request" | "too_big";
+};
+/**
+ * What onRequest answered, as the game gets it: plain JSON (nothing is null), within
+ * REQUEST_LIMITS.maximumAnswerSizeBytes, or a mistake for the game server's errors.
+ */
+export declare function readRequestAnswer(answer: unknown): {
+    answer: unknown;
+} | {
+    mistake: string;
+};
+/** A game server that answers requests. */
+export interface RequestHandler {
+    onRequest?(player: Player, request: unknown, server: Server): unknown;
+}
+/**
+ * Run a game server's onRequest for one request, with a time limit, and say what the game gets. A
+ * game server without onRequest answers no_request_handler. When it throws, answers something that
+ * isn't plain JSON or takes too long, the game gets game_server_error, and failure says why for the
+ * game server's errors.
+ */
+export declare function answerRequest(handler: RequestHandler, player: Player, request: unknown, server: Server): Promise<{
+    answer: unknown;
+} | {
+    code: "no_request_handler";
+} | {
+    code: "game_server_error";
+    failure: string;
+}>;