@zaisma/game-server 1.13.0 → 1.14.0

package/src/chat.js

@@ -9,6 +9,11 @@
  * checkChat sends the players' passes (as your server received them) and the sender's last few messages to
  * Zaisma (POST <issuer>/v1/chat/check), so a phone number sent a few digits at a time is caught too.
  *
+ * A player your server let in from outside Zaisma (kind outside_zaisma) has no pass: give null in their place.
+ * Zaisma counts them as strangers of unknown age, so a message between one and an under-18 account is stopped
+ * (not_allowed_to_chat); between them and adults it's checked as between adults. A message among players from
+ * outside Zaisma only is allowed without asking Zaisma: none of its players is in it, so your own rules apply.
+ *
  * It's for your own server only. In Zaisma rooms the room filters the chat it delivers itself, so a game
  * server running there never sees passes, and checkChat throws a ChatCheckError (own_server_only).
  */
@@ -84,15 +89,26 @@ function rememberText(senderPlayerId, text, nowMs) {
 export async function checkChat({ text, senderPass, receiverPasses }) {
     // Read apart from the destructuring, which is v1's signature as it's locked (test/contracts).
     const isAdultFilterEnabled = arguments[0]?.isAdultFilterEnabled === true;
-    const claims = readClaims(String(senderPass ?? ""));
-    if (typeof claims.sub !== "string" || !isZaismaIssuer(claims.iss) || !Array.isArray(receiverPasses))
+    if (!Array.isArray(receiverPasses) || !receiverPasses.every((pass) => pass === null || typeof pass === "string") || !(senderPass === null || typeof senderPass === "string"))
         return UNCHECKED;
     const message = String(text ?? "");
     if (message.length > CHAT_CHECK_LIMITS.maximumMessageCharacterCount)
         return TOO_LONG;
+    // Among players from outside Zaisma only: no Zaisma player is in it, so the server's own rules apply, and Zaisma never hears of it.
+    const firstPass = [senderPass, ...receiverPasses].find((pass) => typeof pass === "string");
+    if (firstPass === undefined)
+        return { isAllowed: true, reason: null, message: null, hasSwearing: false, hasSlur: false };
+    // Where to ask comes from a pass, the sender's when they have one: they all come from the same issuer for the same game.
+    const claims = readClaims(firstPass);
+    const senderClaims = senderPass === null ? null : readClaims(senderPass);
+    if (typeof claims.sub !== "string" || !isZaismaIssuer(claims.iss) || (senderClaims && typeof senderClaims.sub !== "string"))
+        return UNCHECKED;
     const nowMs = Date.now();
-    const recentTexts = (recentBySender.get(claims.sub) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs).map((sent) => sent.text);
-    rememberText(claims.sub, message, nowMs);
+    // A sender from outside Zaisma has no player ID Zaisma knows, so their last messages aren't sent along.
+    const senderPlayerId = senderClaims ? senderClaims.sub : null;
+    const recentTexts = senderPlayerId ? (recentBySender.get(senderPlayerId) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs).map((sent) => sent.text) : [];
+    if (senderPlayerId)
+        rememberText(senderPlayerId, message, nowMs);
     try {
         const response = await fetch(`${claims.iss}/v1/chat/check`, {
             method: "POST",

package/src/index.d.ts

@@ -7,4 +7,5 @@ export { OUTSIDE_CALL_LIMITS, OutsideCallError, type OutsideCallErrorCode } from
 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, CHAT_ROOM_LIMITS, ChatCheckError, checkChat, type ChatCheck, type ChatCheckOptions, type ChatCheckReason } from "./chat.ts";
 export { guestName, isRoomCode } from "./names.ts";
+export { guestPlayer, signInWithZaismaPlayers, type IdentifyPlayer, type OutsidePlayer, type SignInWithZaismaPlayersOptions } from "./outside-players.ts";
 export { relay } from "./relay.ts";

package/src/index.js

@@ -9,4 +9,5 @@ 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, CHAT_ROOM_LIMITS, ChatCheckError, checkChat } from "./chat.js";
 export { guestName, isRoomCode } from "./names.js";
+export { guestPlayer, signInWithZaismaPlayers } from "./outside-players.js";
 export { relay } from "./relay.js";

package/src/internal.d.ts

@@ -5,6 +5,7 @@ export * from "./database.ts";
 export * from "./dump.ts";
 export * from "./requests.ts";
 export * from "./outside-calls.ts";
+export * from "./outside-players.ts";
 export * from "./schedules.ts";
 export * from "./webhooks.ts";
 export * from "./pass.ts";

package/src/internal.js

@@ -7,6 +7,7 @@ export * from "./database.js";
 export * from "./dump.js";
 export * from "./requests.js";
 export * from "./outside-calls.js";
+export * from "./outside-players.js";
 export * from "./schedules.js";
 export * from "./webhooks.js";
 export * from "./pass.js";

package/src/outside-players.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Players from outside Zaisma, for a game server on your own server: a game played anywhere but its Zaisma
+ * page (exported, on another site, wrapped for a store) has no Zaisma pass, so its game sends a playerToken
+ * instead (Zaisma.setUpOffZaisma) and your server says who that is with startServer's identifyPlayer. Such a
+ * player joins with kind "outside_zaisma", in the same rooms as players from the Zaisma page.
+ *
+ * signInWithZaismaPlayers makes an identifyPlayer for players signed in with Zaisma (Sign in with Zaisma's ID
+ * tokens): the same player ID and name as on Zaisma. guestPlayer is who a player with no token is, when
+ * startServer's outsideGuestsEnabled lets them in: a temporary ID and a generated name, like Zaisma's guests.
+ */
+import { type PublicKey } from "./pass.ts";
+/** Who a player from outside Zaisma is, as identifyPlayer answers: an ID your server keeps for them, and the name others see. */
+export interface OutsidePlayer {
+    /** 1 to 100 characters: a Zaisma player ID for a player signed in with Zaisma, or your own accounts' IDs. */
+    id: string;
+    /** 1 to 40 characters, as other players see it. */
+    name: string;
+}
+/** startServer's identifyPlayer: who a playerToken is, or null when it isn't one your server takes. */
+export type IdentifyPlayer = (playerToken: string, connection: {
+    origin: string | null;
+}) => Promise<OutsidePlayer | null>;
+export interface SignInWithZaismaPlayersOptions {
+    /** Your sign-in apps' IDs (sign_in_app_…), 1 to 20: an ID token for any other app is refused. */
+    signInAppIds: string[];
+    /** Where Sign in with Zaisma runs, the ID tokens' iss: https://zaisma.com unless a local preview of Zaisma. */
+    siteUrl?: string;
+    /** async (isRefreshing) => the ID token keys; by default from <siteUrl>/.well-known/jwks.json, fetched again once on a key it doesn't know. */
+    loadKeys?: (isRefreshing: boolean) => Promise<PublicKey[]>;
+    /** async (playerId) => an account's public profile or null, for a token with no name (signed in without the profile scope). */
+    loadProfile?: (playerId: string) => Promise<{
+        name: string;
+    } | null>;
+}
+export declare const OUTSIDE_PLAYER_LIMITS: {
+    readonly maximumIdCharacterCount: 100;
+    readonly maximumSignInAppCount: 20;
+    /** How far an ID token's exp may be past, for clocks that differ a little. */
+    readonly clockLeewaySec: 60;
+    /** How long the keys and profiles are kept before they're fetched again. */
+    readonly keysKeptMs: 3600000;
+    readonly profileKeptMs: 300000;
+    /** A refresh for a key ID it doesn't know waits this long after the last fetch, so made-up key IDs can't make it fetch on every token. */
+    readonly minimumRefreshIntervalMs: 30000;
+    readonly maximumProfileCount: 10000;
+};
+/**
+ * An identifyPlayer for players signed in with Zaisma: the game signs them in with Sign in with Zaisma and
+ * sends the ID token as its playerToken. The token is checked like any OpenID Connect ID token: RS256 only,
+ * signed by Zaisma's published key, its iss the siteUrl, its aud one of signInAppIds, not expired. The player
+ * is { id, name }: the account's Zaisma player ID, the same as on Zaisma, and its name from the token (or its
+ * public profile when the token has none). Answers null for any token that doesn't check out, and for an
+ * account deleted since; throws only when Zaisma's keys or profiles can't be reached (the runner answers busy).
+ *
+ *   startServer({ gameServer, gameSlug, identifyPlayer: signInWithZaismaPlayers({ signInAppIds: ["sign_in_app_8f3k2m"] }) });
+ */
+export declare function signInWithZaismaPlayers(options: SignInWithZaismaPlayersOptions): IdentifyPlayer;
+/** A player with no token, when startServer's outsideGuestsEnabled lets them in: a temporary player ID and a generated name, as Zaisma's guests have. */
+export declare function guestPlayer(): OutsidePlayer;
+/** What identifyPlayer answered, checked for the runner: the player, with their name tidied, or what was wrong with it. */
+export declare function checkedOutsidePlayer(given: unknown): {
+    player: OutsidePlayer;
+} | {
+    mistake: string;
+};

package/src/outside-players.js

@@ -0,0 +1,162 @@
+/**
+ * Players from outside Zaisma, for a game server on your own server: a game played anywhere but its Zaisma
+ * page (exported, on another site, wrapped for a store) has no Zaisma pass, so its game sends a playerToken
+ * instead (Zaisma.setUpOffZaisma) and your server says who that is with startServer's identifyPlayer. Such a
+ * player joins with kind "outside_zaisma", in the same rooms as players from the Zaisma page.
+ *
+ * signInWithZaismaPlayers makes an identifyPlayer for players signed in with Zaisma (Sign in with Zaisma's ID
+ * tokens): the same player ID and name as on Zaisma. guestPlayer is who a player with no token is, when
+ * startServer's outsideGuestsEnabled lets them in: a temporary ID and a generated name, like Zaisma's guests.
+ */
+import { guestName } from "./names.js";
+import { fromBase64Url } from "./pass.js";
+import { GameServerError, ROOM_LIMITS, tidyRoomInfo } from "./room.js";
+export const OUTSIDE_PLAYER_LIMITS = {
+    maximumIdCharacterCount: 100,
+    maximumSignInAppCount: 20,
+    /** How far an ID token's exp may be past, for clocks that differ a little. */
+    clockLeewaySec: 60,
+    /** How long the keys and profiles are kept before they're fetched again. */
+    keysKeptMs: 3600_000,
+    profileKeptMs: 300_000,
+    /** A refresh for a key ID it doesn't know waits this long after the last fetch, so made-up key IDs can't make it fetch on every token. */
+    minimumRefreshIntervalMs: 30_000,
+    maximumProfileCount: 10_000,
+};
+const RS256 = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+const SIGN_IN_APP_ID = /^sign_in_app_[a-z0-9]+$/;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/** The ID token keys at <siteUrl>/.well-known/jwks.json, kept an hour; a fetch that fails keeps the keys already held. */
+function keysAt(jwksUrl) {
+    let kept = null;
+    let fetchedAtMs = 0;
+    return async (isRefreshing) => {
+        const nowMs = Date.now();
+        if (kept && !isRefreshing && nowMs - kept.fetchedAtMs < OUTSIDE_PLAYER_LIMITS.keysKeptMs)
+            return kept.keys;
+        if (kept && isRefreshing && nowMs - fetchedAtMs < OUTSIDE_PLAYER_LIMITS.minimumRefreshIntervalMs)
+            return kept.keys;
+        fetchedAtMs = nowMs;
+        try {
+            const response = await fetch(jwksUrl);
+            if (!response.ok)
+                throw new Error(`Couldn't load Zaisma's sign-in keys from ${jwksUrl}`);
+            kept = { keys: (await response.json()).keys, fetchedAtMs: nowMs };
+        }
+        catch (error) {
+            if (kept)
+                return kept.keys;
+            throw error;
+        }
+        return kept.keys;
+    };
+}
+/** Accounts' public profiles at Zaisma (https://rooms.zaisma.com/v1/players/<id>), each kept 5 minutes; null when no account has that ID. */
+function profilesAt(profilesUrl) {
+    const kept = new Map();
+    return async (playerId) => {
+        const found = kept.get(playerId);
+        if (found && Date.now() - found.fetchedAtMs < OUTSIDE_PLAYER_LIMITS.profileKeptMs)
+            return found.profile;
+        const response = await fetch(`${profilesUrl}/${encodeURIComponent(playerId)}`);
+        if (response.status !== 200 && response.status !== 404)
+            throw new Error(`Couldn't look up player ${playerId} at ${profilesUrl}`);
+        const profile = response.status === 200 ? (await response.json()).player : null;
+        if (kept.size > OUTSIDE_PLAYER_LIMITS.maximumProfileCount)
+            kept.clear();
+        kept.set(playerId, { profile, fetchedAtMs: Date.now() });
+        return profile;
+    };
+}
+/** A token's header and claims, unchecked, or null when it isn't a JWT. */
+function tokenParts(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const header = JSON.parse(decoder.decode(fromBase64Url(parts[0])));
+        const claims = JSON.parse(decoder.decode(fromBase64Url(parts[1])));
+        if (!header || typeof header !== "object" || !claims || typeof claims !== "object" || Array.isArray(claims))
+            return null;
+        return { header, claims, signature: fromBase64Url(parts[2]) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * An identifyPlayer for players signed in with Zaisma: the game signs them in with Sign in with Zaisma and
+ * sends the ID token as its playerToken. The token is checked like any OpenID Connect ID token: RS256 only,
+ * signed by Zaisma's published key, its iss the siteUrl, its aud one of signInAppIds, not expired. The player
+ * is { id, name }: the account's Zaisma player ID, the same as on Zaisma, and its name from the token (or its
+ * public profile when the token has none). Answers null for any token that doesn't check out, and for an
+ * account deleted since; throws only when Zaisma's keys or profiles can't be reached (the runner answers busy).
+ *
+ *   startServer({ gameServer, gameSlug, identifyPlayer: signInWithZaismaPlayers({ signInAppIds: ["sign_in_app_8f3k2m"] }) });
+ */
+export function signInWithZaismaPlayers(options) {
+    const fields = ["signInAppIds", "siteUrl", "loadKeys", "loadProfile"];
+    if (!options || typeof options !== "object")
+        throw new GameServerError("bad_option", "options", "signInWithZaismaPlayers takes one object of options.", 'Call signInWithZaismaPlayers({ signInAppIds: ["sign_in_app_…"] }).');
+    for (const field of Object.keys(options)) {
+        if (!fields.includes(field))
+            throw new GameServerError("unknown_option", field, `${field} isn't a signInWithZaismaPlayers option.`, `signInWithZaismaPlayers takes: ${fields.join(", ")}.`);
+    }
+    const { signInAppIds, siteUrl = "https://zaisma.com" } = options;
+    if (!Array.isArray(signInAppIds) || signInAppIds.length < 1 || signInAppIds.length > OUTSIDE_PLAYER_LIMITS.maximumSignInAppCount || !signInAppIds.every((id) => typeof id === "string" && SIGN_IN_APP_ID.test(id))) {
+        throw new GameServerError("bad_option", "signInAppIds", "signInAppIds isn't a list of sign-in app IDs.", `Give 1 to ${OUTSIDE_PLAYER_LIMITS.maximumSignInAppCount} of your sign-in apps' IDs, like ["sign_in_app_8f3k2m"] (list_sign_in_apps shows them).`);
+    }
+    if (typeof siteUrl !== "string" || !URL.canParse(siteUrl))
+        throw new GameServerError("bad_option", "siteUrl", "siteUrl isn't a URL.", 'Give where Sign in with Zaisma runs, like "https://zaisma.com".');
+    for (const field of ["loadKeys", "loadProfile"]) {
+        if (options[field] !== undefined && typeof options[field] !== "function")
+            throw new GameServerError("bad_option", field, `${field} isn't a function.`, field === "loadKeys" ? "Give async (isRefreshing) => the keys, as a list." : "Give async (playerId) => { name } or null.");
+    }
+    const loadKeys = options.loadKeys ?? keysAt(`${siteUrl}/.well-known/jwks.json`);
+    const loadProfile = options.loadProfile ?? profilesAt("https://rooms.zaisma.com/v1/players");
+    return async (playerToken) => {
+        const parts = typeof playerToken === "string" ? tokenParts(playerToken) : null;
+        // An ID token, never an access token (at+jwt) or a token signed any other way.
+        if (!parts || parts.header.alg !== "RS256" || parts.header.typ !== "JWT" || typeof parts.header.kid !== "string")
+            return null;
+        const { header, claims } = parts;
+        const nowSec = Math.floor(Date.now() / 1000);
+        if (claims.iss !== siteUrl || typeof claims.aud !== "string" || !signInAppIds.includes(claims.aud))
+            return null;
+        if (typeof claims.exp !== "number" || claims.exp + OUTSIDE_PLAYER_LIMITS.clockLeewaySec <= nowSec)
+            return null;
+        if (typeof claims.sub !== "string" || !claims.sub || claims.sub.length > OUTSIDE_PLAYER_LIMITS.maximumIdCharacterCount)
+            return null;
+        // A key published since the keys were fetched: fetched again once.
+        let jwk = (await loadKeys(false)).find((key) => key.kid === header.kid);
+        if (!jwk)
+            jwk = (await loadKeys(true)).find((key) => key.kid === header.kid);
+        if (!jwk || jwk.kty !== "RSA" || !jwk.n || !jwk.e)
+            return null;
+        const key = await crypto.subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e }, RS256, false, ["verify"]);
+        const [signedHeader, signedClaims] = playerToken.split(".");
+        if (!(await crypto.subtle.verify(RS256, key, parts.signature, encoder.encode(`${signedHeader}.${signedClaims}`))))
+            return null;
+        // A token without the profile scope carries no name: the account's public one. A deleted account has none, and plays no more.
+        const name = typeof claims.name === "string" && claims.name ? claims.name : ((await loadProfile(claims.sub))?.name ?? null);
+        return name ? { id: claims.sub, name } : null;
+    };
+}
+/** A player with no token, when startServer's outsideGuestsEnabled lets them in: a temporary player ID and a generated name, as Zaisma's guests have. */
+export function guestPlayer() {
+    const randomPart = Array.from(crypto.getRandomValues(new Uint8Array(12)), (byte) => byte.toString(36).padStart(2, "0")).join("").slice(0, 20);
+    return { id: `player_${randomPart}`, name: guestName() };
+}
+/** What identifyPlayer answered, checked for the runner: the player, with their name tidied, or what was wrong with it. */
+export function checkedOutsidePlayer(given) {
+    if (!given || typeof given !== "object" || Array.isArray(given))
+        return { mistake: "identifyPlayer answered something other than { id, name } or null." };
+    const { id, name } = given;
+    if (typeof id !== "string" || !id || id.length > OUTSIDE_PLAYER_LIMITS.maximumIdCharacterCount)
+        return { mistake: `identifyPlayer's id isn't text of 1 to ${OUTSIDE_PLAYER_LIMITS.maximumIdCharacterCount} characters.` };
+    const tidied = typeof name === "string" ? tidyRoomInfo({ name }).name : null;
+    if (typeof name !== "string" || !tidied || name.trim().length > ROOM_LIMITS.maximumNameCharacterCount)
+        return { mistake: `identifyPlayer's name isn't text of 1 to ${ROOM_LIMITS.maximumNameCharacterCount} characters.` };
+    return { player: { id, name: tidied } };
+}

package/src/pass.d.ts

@@ -62,8 +62,12 @@ export interface PassClaims {
     iat: number;
     exp: number;
 }
-/** A signed-in Zaisma account, or a guest. */
-export type PlayerKind = "guest" | "account";
+/**
+ * A signed-in Zaisma account, a guest, or a player from outside Zaisma (outside_zaisma): one your own server let
+ * in without a Zaisma pass, by its identifyPlayer (signed in with Zaisma, or your game's own accounts) or as a
+ * guest from elsewhere (outsideGuestsEnabled). Zaisma's rooms and passes never give outside_zaisma.
+ */
+export type PlayerKind = "guest" | "account" | "outside_zaisma";
 /** 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). */
@@ -117,6 +121,7 @@ export declare const RECEIPT_TOKEN_TYPE = "receipt+jwt";
 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;
+export declare function fromBase64Url(text: string): Uint8Array<ArrayBuffer>;
 /** 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 {

package/src/pass.js

@@ -96,7 +96,7 @@ function toBase64Url(bytes) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function fromBase64Url(text) {
+export function fromBase64Url(text) {
     const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
     return Uint8Array.from(binary, (character) => character.charCodeAt(0));
 }

package/src/requests.d.ts

@@ -60,12 +60,14 @@ export declare const REQUEST_LIMITS: {
      * items with 40-character names, 200 friends and 100 blocks) is about 70 KB, with room to spare.
      */
     readonly maximumPassSizeBytes: number;
+    /** A game played off Zaisma sends a playerToken in place of a pass (Zaisma.setUpOffZaisma), to a game server on your own server. */
+    readonly maximumPlayerTokenSizeBytes: 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 type RequestErrorCode = "bad_request" | "too_big" | "bad_pass" | "bad_player_token" | "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>;
@@ -78,7 +80,9 @@ export declare function requestError(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.
+ * (nothing is null). The pass's own size doesn't count. A game server on its developer's own server
+ * (isPlayerTokenTaken) also takes { playerToken, request } from a game played off Zaisma: its token as text,
+ * or null for a guest. Zaisma's rooms never do.
  */
 export declare function readRequestBody(text: string): {
     pass: string;
@@ -86,6 +90,17 @@ export declare function readRequestBody(text: string): {
 } | {
     code: "bad_request" | "too_big";
 };
+export declare function readRequestBody(text: string, isPlayerTokenTaken: boolean): {
+    pass: string;
+    request: unknown;
+} | {
+    playerToken: string | null;
+    request: unknown;
+} | {
+    code: "bad_request" | "too_big";
+};
+/** A playerToken as a game off Zaisma sends it: text up to REQUEST_LIMITS.maximumPlayerTokenSizeBytes, or null for a guest. */
+export declare function isPlayerToken(given: unknown): given is string | null;
 /**
  * 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.

package/src/requests.js

@@ -17,6 +17,8 @@ export const REQUEST_LIMITS = {
      * items with 40-character names, 200 friends and 100 blocks) is about 70 KB, with room to spare.
      */
     maximumPassSizeBytes: 96 * 1024,
+    /** A game played off Zaisma sends a playerToken in place of a pass (Zaisma.setUpOffZaisma), to a game server on your own server. */
+    maximumPlayerTokenSizeBytes: 8 * 1024,
     /** What onRequest answers, as JSON. */
     maximumAnswerSizeBytes: 1024 * 1024,
     /** How long onRequest may take, awaiting the database included, before the request fails. */
@@ -26,6 +28,7 @@ export const REQUEST_ERROR_TEXT = {
     bad_request: "Requests are JSON with the player's pass and the game's request: { pass, request }.",
     too_big: `Requests are up to ${REQUEST_LIMITS.maximumRequestSizeBytes / 1024} KB.`,
     bad_pass: "Your player pass isn't valid for this game.",
+    bad_player_token: "This server doesn't know this player. Sign in again.",
     account_needed: "Playing online needs a Zaisma account. Sign in on the game's page to play.",
     game_not_open_to_player: "This game isn't open to this account.",
     game_unavailable: "This game isn't available right now.",
@@ -41,6 +44,7 @@ export const REQUEST_ERROR_HTTP_STATUS = {
     bad_request: 400,
     too_big: 413,
     bad_pass: 401,
+    bad_player_token: 401,
     account_needed: 403,
     game_not_open_to_player: 403,
     game_unavailable: 404,
@@ -55,11 +59,7 @@ export const REQUEST_ERROR_HTTP_STATUS = {
 export function requestError(code, message) {
     return { error: { code, message: message || REQUEST_ERROR_TEXT[code] } };
 }
-/**
- * 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 function readRequestBody(text) {
+export function readRequestBody(text, isPlayerTokenTaken = false) {
     let body;
     try {
         body = JSON.parse(text);
@@ -69,13 +69,20 @@ export function readRequestBody(text) {
     }
     if (!body || typeof body !== "object" || Array.isArray(body))
         return { code: "bad_request" };
-    const { pass, request } = body;
-    if (typeof pass !== "string" || pass.length > REQUEST_LIMITS.maximumPassSizeBytes)
+    const { pass, playerToken, request } = body;
+    const isOutside = isPlayerTokenTaken && pass === undefined && isPlayerToken(playerToken);
+    if (!isOutside && (typeof pass !== "string" || pass.length > REQUEST_LIMITS.maximumPassSizeBytes))
         return { code: "bad_request" };
     const requestText = request === undefined ? "null" : JSON.stringify(request);
     if (new TextEncoder().encode(requestText).length > REQUEST_LIMITS.maximumRequestSizeBytes)
         return { code: "too_big" };
-    return { pass, request: request === undefined ? null : request };
+    if (isOutside)
+        return { playerToken: playerToken, request: request === undefined ? null : request };
+    return { pass: pass, request: request === undefined ? null : request };
+}
+/** A playerToken as a game off Zaisma sends it: text up to REQUEST_LIMITS.maximumPlayerTokenSizeBytes, or null for a guest. */
+export function isPlayerToken(given) {
+    return given === null || (typeof given === "string" && given.length > 0 && new TextEncoder().encode(given).length <= REQUEST_LIMITS.maximumPlayerTokenSizeBytes);
 }
 /**
  * What onRequest answered, as the game gets it: plain JSON (nothing is null), within

package/src/room.d.ts

@@ -17,7 +17,7 @@ export interface Player {
     id: string;
     /** The account's name, or a guest's generated one like "Swift Fox 42". */
     name: string;
-    /** A signed-in Zaisma account, or a guest. */
+    /** A signed-in Zaisma account, a guest, or a player your own server let in from outside Zaisma (outside_zaisma). */
     kind: PlayerKind;
     /**
      * The permanent items the account owns in this game, by item_name, from the pass it joined with (its
@@ -1117,7 +1117,7 @@ export type ClientMessage = {
  * the game became unavailable, its kept room was deleted, or no players were left for its spectators.
  */
 export type EndReason = "game" | "hosting_paused" | "game_server_stopped" | "game_unavailable" | "kept_room_deleted" | "no_players";
-export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
+export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "bad_player_token" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
 export declare const ERROR_TEXT: Record<RoomErrorCode, string>;
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export declare const HOSTING_PAUSED_END_MESSAGE = "This game's hosting is paused, so this match has ended. New rooms open again when the month resets or its developer adds credit.";
@@ -1250,6 +1250,12 @@ export interface PlayerChatSettings {
     whoCanChat: "nobody" | "friends" | "anyone";
     chatGroupId: string | null;
 }
+/**
+ * The chat settings of a player your own server let in from outside Zaisma (outside_zaisma): they chat with
+ * anyone who chats with anyone, in no chat group, and Zaisma's chat check stops any message between them and
+ * an under-18 account. Zaisma's chat groups are chat_group_… IDs, so none is ever this one.
+ */
+export declare const OUTSIDE_ZAISMA_CHAT_SETTINGS: PlayerChatSettings;
 /** A checked pass's chat settings, for RoomCore.setChatSettings: null for a guest. A setting this version doesn't know chats with nobody. */
 export declare function chatSettingsOf(claims: PassClaims): PlayerChatSettings | null;
 /** A chat message from a client as readChatMessage found it, for startChat to check. */
@@ -1531,7 +1537,9 @@ export declare class RoomCore<S = any> {
     canChat(playerId: string): boolean;
     /**
      * Whether one player's chat may reach another, canChat's rule on passes (pass.ts): two accounts in the
-     * same chat group with no block either way, friends unless both chat with anyone.
+     * same chat group with no block either way, friends unless both chat with anyone. A player from outside
+     * Zaisma is in no chat group: they chat with anyone who chats with anyone, and Zaisma's chat check stops
+     * what would reach an under-18 account or come from one.
      */
     private mayChat;
     /** Who a player's chat may reach: the players in the match (or those of toPlayerIds in it), never spectators, kept only where they may chat. */

package/src/room.js

@@ -312,6 +312,7 @@ export const ERROR_TEXT = {
     too_fast: "Too many messages. Slow down.",
     bad_message: "The room couldn't read or use that message.",
     bad_pass: "Your player pass isn't valid for this game.",
+    bad_player_token: "This server doesn't know this player. Sign in again.",
     no_hello: "Send your player pass first.",
     not_allowed: "Only the game server or the room's host can do that.",
     game_unavailable: "This game isn't available right now.",
@@ -411,6 +412,12 @@ export function checkRoomData(given, maximumSizeBytes) {
 export function errorMessage(code, message, details) {
     return JSON.stringify({ type: "error", code, message: message || ERROR_TEXT[code], ...details });
 }
+/**
+ * The chat settings of a player your own server let in from outside Zaisma (outside_zaisma): they chat with
+ * anyone who chats with anyone, in no chat group, and Zaisma's chat check stops any message between them and
+ * an under-18 account. Zaisma's chat groups are chat_group_… IDs, so none is ever this one.
+ */
+export const OUTSIDE_ZAISMA_CHAT_SETTINGS = { whoCanChat: "anyone", chatGroupId: "outside_zaisma" };
 /** A checked pass's chat settings, for RoomCore.setChatSettings: null for a guest. A setting this version doesn't know chats with nobody. */
 export function chatSettingsOf(claims) {
     if (claims.kind !== "account")
@@ -971,14 +978,17 @@ export class RoomCore {
     }
     /**
      * Whether one player's chat may reach another, canChat's rule on passes (pass.ts): two accounts in the
-     * same chat group with no block either way, friends unless both chat with anyone.
+     * same chat group with no block either way, friends unless both chat with anyone. A player from outside
+     * Zaisma is in no chat group: they chat with anyone who chats with anyone, and Zaisma's chat check stops
+     * what would reach an under-18 account or come from one.
      */
     mayChat(senderPlayerId, receiverPlayerId) {
         if (senderPlayerId === receiverPlayerId || !this.canChat(senderPlayerId) || !this.canChat(receiverPlayerId) || this.hasBlockBetween(senderPlayerId, receiverPlayerId))
             return false;
         const sender = this.chatSettings.get(senderPlayerId);
         const receiver = this.chatSettings.get(receiverPlayerId);
-        if (sender.chatGroupId !== receiver.chatGroupId)
+        const isOutside = (settings) => settings.chatGroupId === OUTSIDE_ZAISMA_CHAT_SETTINGS.chatGroupId;
+        if (sender.chatGroupId !== receiver.chatGroupId && !isOutside(sender) && !isOutside(receiver))
             return false;
         return (sender.whoCanChat === "anyone" && receiver.whoCanChat === "anyone") || this.areFriends(senderPlayerId, receiverPlayerId);
     }