@zaisma/game-server 1.13.0 → 1.14.0

package/bin/node-parts.js

@@ -289,7 +289,7 @@ export function secretsFromEnvironment() {
   return Object.freeze(Object.fromEntries(Object.entries(process.env).filter(([, environmentValue]) => typeof environmentValue === "string")));
 }
 
-const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl", "webtransportPort", "certificatePath", "certificateKeyPath"];
+const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl", "webtransportPort", "certificatePath", "certificateKeyPath", "identifyPlayer", "outsideGuestsEnabled"];
 
 /**
  * Check what startServer was given: unknown options and options of the wrong kind are a GameServerError,
@@ -325,6 +325,10 @@ export function checkedStartServerOptions(given, issuerUrlDefault) {
   if (options.roomStateFile !== undefined && options.roomStateFile !== null && !isText(options.roomStateFile)) throw bad("roomStateFile", "a file path", "Give a file path as text, like \"zaisma-room-states.sqlite\", or null to keep no states.");
   if (options.zaismaKey !== undefined && !isText(options.zaismaKey)) throw bad("zaismaKey", "an API key", "Give an API key with purchase_access write for this game as text, or leave it out to use ZAISMA_KEY.");
   if (options.developerApiUrl !== undefined && (!isText(options.developerApiUrl) || !URL.canParse(options.developerApiUrl))) throw bad("developerApiUrl", "a URL", 'Give the address of Zaisma\'s developer API, like "https://zaisma.com/api/dev".');
+  // Players from outside Zaisma (games played off their Zaisma page): who a playerToken is, and whether players with none come in as guests.
+  if (options.identifyPlayer !== undefined && !isFunction(options.identifyPlayer)) throw bad("identifyPlayer", "a function", "Give async (playerToken, { origin }) => ({ id, name }) or null, like signInWithZaismaPlayers({ signInAppIds }) makes.");
+  options.outsideGuestsEnabled ??= false;
+  if (typeof options.outsideGuestsEnabled !== "boolean") throw bad("outsideGuestsEnabled", "true or false", "Give true to let players with no playerToken in as guests, or false (the default).");
   // The fast lane (WebTransport): its UDP port and the certificate it holds itself, all three or none.
   const fastLaneFields = ["webtransportPort", "certificatePath", "certificateKeyPath"];
   const missingFastLaneFields = fastLaneFields.filter((field) => options[field] === undefined);

package/bin/node.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from "node:http";
-import type { GameDatabase, GameServer, PublicKey } from "../src/index.js";
+import type { GameDatabase, GameServer, IdentifyPlayer, PublicKey } from "../src/index.js";
 
 /** What startServer takes. Only gameServer and gameSlug are required; the rest have the defaults named here. */
 export interface StartServerOptions {
@@ -41,6 +41,15 @@ export interface StartServerOptions {
   certificatePath?: string;
   /** The fast lane's certificate key, a PEM file (Let's Encrypt's privkey.pem). */
   certificateKeyPath?: string;
+  /**
+   * Who a player from outside Zaisma is: a game played off its Zaisma page sends a playerToken in place of a pass
+   * (Zaisma.setUpOffZaisma), and this answers { id, name } for it, or null to refuse (bad_player_token). They join
+   * with kind "outside_zaisma". signInWithZaismaPlayers({ signInAppIds }) makes one for Sign in with Zaisma; your
+   * own checks your game's own accounts. One that throws answers busy. None by default: only Zaisma passes.
+   */
+  identifyPlayer?: IdentifyPlayer;
+  /** Let players from outside Zaisma with no token (playerToken: null) in as guests (guestPlayer): false by default. */
+  outsideGuestsEnabled?: boolean;
 }
 
 export interface RunningServer {

package/bin/node.js

@@ -7,7 +7,9 @@
 //
 // Players connect to wss://your-server/v1/rooms/<game>/<code>, the same address
 // layout as Zaisma rooms, and prove who they are with Zaisma player passes,
-// checked against the keys Zaisma publishes. Put it behind HTTPS (Caddy, nginx,
+// checked against the keys Zaisma publishes. A game played off its Zaisma page sends a playerToken instead
+// (Zaisma.setUpOffZaisma), and identifyPlayer says who that is (signInWithZaismaPlayers for players signed in
+// with Zaisma, or your own accounts); outsideGuestsEnabled lets players with none in as guests. Put it behind HTTPS (Caddy, nginx,
 // a Cloudflare Tunnel) and add the address to your game's own servers (own_server_urls, or zaisma own-servers).
 // The game's requests (onRequest) come to POST /v1/requests/<game> on the same port, and its
 // schedules (onSchedule) run while it's up, at the minutes their crons give in UTC. A Zaisma webhook
@@ -24,7 +26,7 @@ import { createServer } from "node:http";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
-import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, chatSettingsOf, checkChat, readChatMessage, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, clientIdle, defineGameServer, errorMessage, newServer, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
+import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, OUTSIDE_ZAISMA_CHAT_SETTINGS, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, chatSettingsOf, checkChat, readChatMessage, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, checkedOutsidePlayer, clientIdle, defineGameServer, errorMessage, guestPlayer, newServer, isPlayerToken, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
 import { OutsideCallError } from "../src/outside-calls.js";
 import { startFastLane } from "./fast-lane.js";
 import { checkedStartServerOptions, localDatabase, localRoomStates, passKeysFrom, profilesFrom, receiptKeysFrom, secretsFromEnvironment } from "./node-parts.js";
@@ -74,11 +76,15 @@ const CATCH_UP_MS = 50;
  * the ZAISMA_KEY environment variable) and developerApiUrl (Zaisma's developer API; by default https://zaisma.com/api/dev).
  * webtransportPort (a UDP port), certificatePath and certificateKeyPath (the server's certificate and its key,
  * PEM files), all three or none, also serve the fast lane (WebTransport) beside the WebSocket.
+ * identifyPlayer (async (playerToken, { origin }) => ({ id, name }) or null; none by default) says who a player from
+ * outside Zaisma is by the playerToken their game sent (signInWithZaismaPlayers makes one for Sign in with Zaisma),
+ * and outsideGuestsEnabled (false by default) lets players with no token (playerToken: null) in as guests (guestPlayer).
+ * Both join with kind "outside_zaisma".
  * Answers { close(), httpServer, fastLaneReady }: close() saves every room first and finishes once the server
  * has stopped; fastLaneReady settles once the fast lane listens (at once without one), or rejects saying why it can't.
  */
 export function startServer(options) {
-  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite", zaismaKey = process.env.ZAISMA_KEY, developerApiUrl = "https://zaisma.com/api/dev", webtransportPort, certificatePath, certificateKeyPath } = checkedStartServerOptions(options, PASS_ISSUER_URL);
+  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite", zaismaKey = process.env.ZAISMA_KEY, developerApiUrl = "https://zaisma.com/api/dev", webtransportPort, certificatePath, certificateKeyPath, identifyPlayer, outsideGuestsEnabled } = checkedStartServerOptions(options, PASS_ISSUER_URL);
   const definition = defineGameServer(gameServer);
   // Exactly once needs Zaisma's record of what's handled: without a key, purchases would come twice, so it doesn't start.
   if ((definition.onPurchase || definition.onRefund) && !zaismaKey) {
@@ -125,7 +131,7 @@ export function startServer(options) {
    * account's name from its public profile, and the pass's claims, for blocks between players. Null
    * for an account deleted since; PassError for a bad pass.
    */
-  async function playerFrom(pass) {
+  async function passPlayer(pass) {
     const claims = await verifyPass(pass, await loadPassKeys(), { gameSlug, issuerUrl }).catch(async (error) => {
       // A new key may have been published since we cached them.
       if (error instanceof PassError && error.code === "unknown_key") return verifyPass(pass, await loadPassKeys(true), { gameSlug, issuerUrl });
@@ -139,8 +145,43 @@ export function startServer(options) {
     return name ? { player: { id: claims.sub, name, kind: claims.kind === "account" ? "account" : "guest", ...owned }, claims } : null;
   }
 
-  // Requests from the game to onRequest, outside any room: POST /v1/requests/<game> with { pass, request },
-  // sent as text/plain JSON so browsers need no preflight. Answers { answer } or { error: { code, message } }.
+  /**
+   * Who a hello or request is from: by a Zaisma pass, or, from a game played off Zaisma, by the playerToken it
+   * sent, as identifyPlayer says, or as a guest when there's none and outsideGuestsEnabled. Answers { player, claims }
+   * (claims null for a player from outside Zaisma, who has no pass), or { code } when they can't come in.
+   */
+  async function playerFrom({ pass, playerToken, origin }) {
+    if (typeof pass === "string") {
+      try {
+        return (await passPlayer(pass)) ?? { code: "bad_pass" };
+      } catch (error) {
+        if (error instanceof PassError) return { code: "bad_pass" };
+        // Zaisma couldn't be reached for the account's name: the player tries again, nothing crashes.
+        console.error("Couldn't check a player's pass:", error);
+        return { code: "busy" };
+      }
+    }
+    const outside = (player) => ({ player: { ...player, kind: "outside_zaisma" }, claims: null });
+    if (playerToken === null) return outsideGuestsEnabled ? outside(guestPlayer()) : { code: "bad_player_token", message: "This server takes players signed in, not guests: the game gives a playerToken." };
+    if (!identifyPlayer) return { code: "bad_player_token", message: "This server takes players from Zaisma's pages only." };
+    let identified;
+    try {
+      identified = await identifyPlayer(playerToken, { origin: origin ?? null });
+    } catch (error) {
+      console.error("Game server error in identifyPlayer:", error);
+      return { code: "busy" };
+    }
+    if (identified === null) return { code: "bad_player_token" };
+    const checked = checkedOutsidePlayer(identified);
+    if ("mistake" in checked) {
+      console.error(`Game server error in identifyPlayer: ${checked.mistake}`);
+      return { code: "bad_player_token" };
+    }
+    return outside(checked.player);
+  }
+
+  // Requests from the game to onRequest, outside any room: POST /v1/requests/<game> with { pass, request }, or
+  // { playerToken, request } from a game played off Zaisma, sent as text/plain JSON so browsers need no preflight. Answers { answer } or { error: { code, message } }.
   function answerHttp(request, response) {
     if (request.url === "/v1/webhooks") return answerWebhook(request, response);
     const origin = request.headers.origin;
@@ -171,16 +212,10 @@ export function startServer(options) {
     request.on("end", async () => {
       try {
         if (isTooBig) return fail("too_big");
-        const body = readRequestBody(text);
+        const body = readRequestBody(text, true);
         if ("code" in body) return fail(body.code);
-        let checked;
-        try {
-          checked = await playerFrom(body.pass);
-        } catch (error) {
-          if (error instanceof PassError) return fail("bad_pass");
-          throw error;
-        }
-        if (!checked) return fail("bad_pass");
+        const checked = await playerFrom({ ...body, origin });
+        if (checked.code) return fail(checked.code, checked.message);
         const outcome = await answerRequest(definition, checked.player, body.request, server);
         if ("answer" in outcome) return reply(200, { answer: outcome.answer });
         if (outcome.code === "game_server_error") console.error("Game server error in onRequest:", outcome.failure);
@@ -512,8 +547,10 @@ export function startServer(options) {
     if (!started) return;
     let check = { isAllowed: true, reason: null, message: null, hasSwearing: false, hasSlur: false };
     if (started.receiverPlayerIds.length) {
-      const receiverPasses = started.receiverPlayerIds.map((id) => room.passTexts.get(id)).filter((pass) => typeof pass === "string");
-      check = await checkChat({ text: started.text, senderPass: room.passTexts.get(playerId) ?? "", receiverPasses, isAdultFilterEnabled: definition.adultChatFilterEnabled === true });
+      // A player from outside Zaisma goes as null: Zaisma stops their chat with under-18 accounts, and doesn't hear chat among them alone.
+      const passOf = (id) => (room.core.players.get(id)?.kind === "outside_zaisma" ? null : (room.passTexts.get(id) ?? ""));
+      const receiverPasses = started.receiverPlayerIds.map(passOf);
+      check = await checkChat({ text: started.text, senderPass: passOf(playerId), receiverPasses, isAdultFilterEnabled: definition.adultChatFilterEnabled === true });
     }
     if (check.isAllowed) room.core.deliverChat(playerId, chat.chatNumber, started.receiverPlayerIds, { text: started.text, hasSwearing: check.hasSwearing, hasSlur: check.hasSlur });
     else room.core.stopChat(playerId, chat.chatNumber, check.reason ?? "unchecked", check.message ?? "");
@@ -621,13 +658,17 @@ export function startServer(options) {
         return;
       }
       let pass;
+      let playerToken;
       let made = {};
       // Come to watch, not to play (joinRoom({ isSpectator: true })).
       let isSpectator = false;
       try {
         const hello = JSON.parse(text ?? "");
-        if (hello.type !== "hello" || typeof hello.pass !== "string") return refuse("no_hello");
-        pass = hello.pass;
+        // A Zaisma pass, or from a game played off Zaisma, its playerToken (null for a guest).
+        const isOutside = hello.pass === undefined && isPlayerToken(hello.playerToken);
+        if (hello.type !== "hello" || (typeof hello.pass !== "string" && !isOutside)) return refuse("no_hello");
+        if (isOutside) playerToken = hello.playerToken;
+        else pass = hello.pass;
         isSpectator = hello.isSpectator === true;
         if (hello.room && typeof hello.room === "object") made = { ...(hello.room.isListed === true ? { isListed: true } : {}), ...(hello.room.friendJoinsEnabled === false ? { friendJoinsEnabled: false } : {}), ...tidyRoomInfo(hello.room) };
         made.clientIdle = clientIdle(hello);
@@ -637,16 +678,8 @@ export function startServer(options) {
       } catch {
         return refuse("no_hello");
       }
-      let checked;
-      try {
-        checked = await playerFrom(pass);
-      } catch (error) {
-        if (error instanceof PassError) return refuse("bad_pass");
-        // Zaisma couldn't be reached for the account's name: the player tries again, nothing crashes.
-        console.error("Couldn't check a player's pass:", error);
-        return refuse("busy");
-      }
-      if (!checked) return refuse("bad_pass");
+      const checked = await playerFrom({ pass, playerToken, origin });
+      if (checked.code) return refuse(checked.code, checked.message);
       const { player, claims } = checked;
       clearTimeout(helloTimer);
       // A spectator watches a match: one with nobody in it isn't running, and a spectator never starts one.
@@ -663,8 +696,14 @@ export function startServer(options) {
       // Blocks between accounts come in their passes: this player's and those of everyone the room remembers.
       // Spectators send nothing, so nothing of theirs reaches a player to block.
       // Who the player may chat with, from their pass: the room keeps it, and the game never sees it. Spectators send nothing, chat included.
-      room.core.setChatSettings(player.id, isSpectator ? null : chatSettingsOf(claims));
-      if (!isSpectator) {
+      // A player from outside Zaisma has no pass: no account blocks or friends, and chat as OUTSIDE_ZAISMA_CHAT_SETTINGS says.
+      room.core.setChatSettings(player.id, isSpectator ? null : claims ? chatSettingsOf(claims) : OUTSIDE_ZAISMA_CHAT_SETTINGS);
+      if (!isSpectator && !claims) {
+        room.passes.delete(player.id);
+        room.passTexts.delete(player.id);
+        room.core.setAccountBlocks(player.id, []);
+        room.core.setFriends(player.id, []);
+      } else if (!isSpectator) {
         room.passes.set(player.id, claims);
         room.passTexts.set(player.id, pass);
         for (const id of room.passes.keys()) {

package/package.json

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

package/sdk/zaisma.d.ts

@@ -26,7 +26,9 @@
  *
  * Player passes, for rooms and your own servers, need the game played on its zaisma.com page, which
  * checks the browser on Play: joining fails with `error.code` "unchecked" when it couldn't, or when the
- * game was opened anywhere else, and "not_on_zaisma" when the game isn't hosted on Zaisma at all.
+ * game was opened anywhere else. A game played off Zaisma (exported, on another site, wrapped for a store)
+ * plays online against your own game server only: call {@link Zaisma.setUpOffZaisma} first, and give
+ * joinRoom and server.request a serverUrl; without them they fail with "not_on_zaisma".
  *
  * @example
  * const room = await Zaisma.joinRoom();         // joins ?room=CODE if the link has one, else makes a room
@@ -140,8 +142,9 @@ declare namespace Zaisma {
    * refused (the game server's canJoin said no; the message is its refusalMessage), hosting_paused (the
    * game's hosting is paused this month: its free allowance or its developer's budget or credit is used). No player pass: unchecked, or account_needed for a
    * guest when the game needs accounts (see Zaisma.player.getPass()). The
-   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, bad_transport, not_on_zaisma (the game isn't hosted
-   * on Zaisma, serverUrl or not; serverUrl points a game hosted on Zaisma at your own server). Or connection_closed (the connection closed first, say the game left or the player
+   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, bad_transport, not_on_zaisma (the game is played
+   * off Zaisma without a serverUrl, or before {@link setUpOffZaisma}). Off Zaisma, bad_player_token: your server
+   * didn't take the playerToken (get the player a new one and call setUpOffZaisma again). Or connection_closed (the connection closed first, say the game left or the player
    * joined from another tab) and request_failed (Zaisma didn't answer). {@link ErrorCode} has them all.
    *
    * @example
@@ -154,6 +157,40 @@ declare namespace Zaisma {
    */
   function joinRoom(joinOptions?: JoinOptions): Promise<Room>;
 
+  /**
+   * Set up a game played off Zaisma (exported, on another site, wrapped for a store) to play online against
+   * your own game server. Off Zaisma there's no Zaisma pass, so joinRoom and server.request with a serverUrl
+   * send the playerToken in its place, and your server says who the player is (startServer's identifyPlayer):
+   * a Sign in with Zaisma ID token (same player ID and name as on Zaisma), your game's own token, or null for
+   * a guest when your server lets guests in (outsideGuestsEnabled). They join with kind "outside_zaisma",
+   * in the same rooms as players from your Zaisma page.
+   *
+   * On a Zaisma page it changes nothing and resolves { isOffZaisma: false }, so the same code runs in both
+   * places. Call it again to replace the token (a new sign-in, or signing out); rooms use the newest one when
+   * they reconnect. Off Zaisma there's no Zaisma bar, saves, buy sheet, friends or room lists.
+   *
+   * Fails with error.code unknown_option, bad_game_slug (not a game slug) and bad_player_token (not text up to 8 KB, or null).
+   *
+   * @example
+   * await Zaisma.setUpOffZaisma({ gameSlug: "star-raiders", playerToken: idToken });
+   * const room = await Zaisma.joinRoom({ serverUrl: "wss://play.example.com" });
+   */
+  function setUpOffZaisma(setUpOptions: SetUpOffZaismaOptions): Promise<OffZaismaSetup>;
+
+  /** Options for {@link setUpOffZaisma}. */
+  interface SetUpOffZaismaOptions {
+    /** Your game's slug, as its Zaisma link names it, like "star-raiders": the address your server's rooms and requests take. */
+    gameSlug: string;
+    /** The player's token for your own server, text up to 8 KB: a Sign in with Zaisma ID token or your game's own. Null or left out for a guest. */
+    playerToken?: string | null;
+  }
+
+  /** What {@link setUpOffZaisma} answers. */
+  interface OffZaismaSetup {
+    /** False on a Zaisma page (nothing changed); true elsewhere, where joins and requests now carry the playerToken. */
+    isOffZaisma: boolean;
+  }
+
   /** Room browsing: the game's listed rooms, which show on its Zaisma page and to the game itself. */
   const rooms: Rooms;
 
@@ -982,8 +1019,9 @@ declare namespace Zaisma {
      * seconds; you see why with the game server's errors), hosting_paused (the game's hosting
      * on Zaisma is paused this month: its free allowance or its developer's budget or credit is used), too_big, bad_request (not plain JSON), slow_down
      * (over about 120 a minute from one address), bad_pass, account_needed, unchecked,
-     * game_unavailable, bad_origin, busy, bad_server_url, not_on_zaisma (the game isn't hosted
-     * on Zaisma, serverUrl or not), unknown_option and request_failed.
+     * game_unavailable, bad_origin, busy, bad_server_url, not_on_zaisma (the game is played off
+     * Zaisma without a serverUrl, or before {@link Zaisma.setUpOffZaisma}), bad_player_token (off Zaisma,
+     * your server didn't take the playerToken), unknown_option and request_failed.
      *
      * @example
      * const top = await Zaisma.server.request({ type: "leaderboard" });
@@ -1488,8 +1526,11 @@ declare namespace Zaisma {
     awayReason: "idle" | "hidden" | "lost" | null;
   }
 
-  /** A signed-in Zaisma account, or a guest. More values may come; treat an unknown one as "guest". */
-  type PlayerKind = "guest" | "account";
+  /**
+   * A signed-in Zaisma account, a guest, or a player your own server let in from outside Zaisma
+   * (outside_zaisma: a game played off Zaisma, {@link setUpOffZaisma}). More values may come; treat an unknown one as "guest".
+   */
+  type PlayerKind = "guest" | "account" | "outside_zaisma";
 
   /** What anyone sees of an account on its profile, zaisma.com/@username ({@link player.getProfile}). */
   interface PlayerProfile {
@@ -1627,6 +1668,7 @@ declare namespace Zaisma {
    * - game_not_open_to_player: the account is younger than the game's minimum age (set on the dashboard); the game never learns its age.
    * - game_unavailable: the game can't be played right now.
    * - bad_pass: the player pass wasn't accepted (the SDK gets a new one and tries once more).
+   * - bad_player_token: off Zaisma, your own server didn't take the playerToken ({@link setUpOffZaisma}); the game gets the player a new one.
    * - bad_origin: the connection didn't come from the game's own page.
    * - too_big: a message over 16 KB, or joinData over 4 KB.
    * - too_fast: more messages than the room takes (about 30 a second).
@@ -1642,6 +1684,8 @@ declare namespace Zaisma {
    * - chat_not_allowed, chat_empty, chat_too_long, chat_too_fast: {@link Room.chat} refused (they reject its promise, not the "error" event); chat_not_here: the room's server doesn't take chat.
    *
    * More codes may come within v1: handle one you don't know like an error you can show (its message).
+   *
+   * More values may come; treat an unknown one as "request_failed".
    */
   type RoomErrorCode =
     | "room_full"
@@ -1654,6 +1698,7 @@ declare namespace Zaisma {
     | "game_not_open_to_player"
     | "game_unavailable"
     | "bad_pass"
+    | "bad_player_token"
     | "bad_origin"
     | "too_big"
     | "too_fast"
@@ -1679,6 +1724,7 @@ declare namespace Zaisma {
    * - bad_request: not plain JSON with the player's pass.
    * - too_big: a request over 16 KB.
    * - bad_pass: the player pass wasn't accepted (the SDK gets a new one and tries once more).
+   * - bad_player_token: off Zaisma, your own server didn't take the playerToken ({@link setUpOffZaisma}); the game gets the player a new one.
    * - account_needed: the player is a guest, and the game needs a Zaisma account for multiplayer or the whole game.
    * - game_not_open_to_player: the account is younger than the game's minimum age (set on the dashboard); the game never learns its age.
    * - game_unavailable: the game can't be played right now.
@@ -1688,11 +1734,14 @@ declare namespace Zaisma {
    * - slow_down: too many requests from this address; try again in a minute.
    * - bad_origin: the request didn't come from the game's own page.
    * - busy: Zaisma couldn't answer right now; try again soon.
+   *
+   * More values may come; treat an unknown one as "request_failed".
    */
   type RequestErrorCode =
     | "bad_request"
     | "too_big"
     | "bad_pass"
+    | "bad_player_token"
     | "account_needed"
     | "game_not_open_to_player"
     | "game_unavailable"
@@ -1711,7 +1760,8 @@ declare namespace Zaisma {
    * - zaisma_rooms_not_used: the game doesn't use Zaisma rooms.
    * - bad_report: a report whose reason isn't a {@link ReportReason}, or whose player ID isn't one.
    * - bad_origin: the call didn't come from the game's own page.
-   * - not_on_zaisma: the game isn't hosted on Zaisma, so it has no player passes, sign-in or room lists, and joinRoom needs a serverUrl.
+   * - not_on_zaisma: the game is played off Zaisma, so it has no player passes, sign-in or room lists; joinRoom and server.request need {@link setUpOffZaisma} and a serverUrl.
+   * - bad_game_slug: {@link setUpOffZaisma}'s gameSlug isn't a game slug: 1 to 40 lowercase letters, digits or hyphens.
    * - sign_in_declined: the player chose Not now when the game asked them to sign in ({@link player.signIn}) or showed the "Keep your progress" card ({@link player.offerAccount}).
    * - account_offer_too_soon: the "Keep your progress" card already showed this visit, or the player chose Not now in the last 3 days ({@link player.offerAccount}).
    * - cloud_saves_off: the game has cloud saves off, so it has no saves on players' accounts ({@link saves}).
@@ -1752,6 +1802,7 @@ declare namespace Zaisma {
     | "bad_report"
     | "bad_origin"
     | "not_on_zaisma"
+    | "bad_game_slug"
     | "sign_in_declined"
     | "account_offer_too_soon"
     | "cloud_saves_off"

package/sdk/zaisma.js

@@ -6,8 +6,11 @@
  * together; test/node/sdk-types.test.ts checks that they match.
  *
  * On Zaisma, the games Worker defines __ZAISMA__ before this file with the rooms address, the game and
- * the site. A game that isn't hosted on Zaisma gets "not_on_zaisma" for online play, serverUrl or not; serverUrl points a
- * game hosted on Zaisma at your own server.
+ * the site; serverUrl points a game played there at your own server. Played anywhere else (exported, on
+ * another site, wrapped for a store), a game plays online against your own server only: after
+ * Zaisma.setUpOffZaisma({ gameSlug, playerToken }), joinRoom and server.request with a serverUrl send the
+ * playerToken in place of a Zaisma pass, and your server says who that is (its identifyPlayer). Saves, the buy
+ * sheet, friends and room lists stay on Zaisma, and so does the Zaisma bar.
  */
 (function () {
   "use strict";
@@ -18,6 +21,7 @@
   var OWN_SERVER_URL = /^(wss|https):\/\/[^/]/;
 
   // What each call takes. Anything else is refused, so a misspelled or old option never goes quietly unused.
+  var SET_UP_OFF_ZAISMA_OPTIONS = ["gameSlug", "playerToken"];
   var JOIN_OPTIONS = ["roomCode", "serverUrl", "transport", "isListed", "friendJoinsEnabled", "name", "labels", "joinData", "idleTimeoutSec", "idleCheckEnabled", "isSpectator"];
   // quickJoin finds Zaisma rooms, so it takes no serverUrl.
   var QUICK_JOIN_OPTIONS = ["isListed", "friendJoinsEnabled", "name", "labels", "joinData", "idleTimeoutSec", "idleCheckEnabled", "region"];
@@ -76,6 +80,13 @@
   var DEFAULT_SMOOTHING_DELAY_MS = 100;
   var KEPT_VIEWS_DURATION_MS = 1000;
 
+  /** A game's slug, as its Zaisma link names it. */
+  var GAME_SLUG = /^[a-z0-9-]{1,40}$/;
+  /** The longest playerToken a game off Zaisma sends its own server, as UTF-8. */
+  var MAXIMUM_PLAYER_TOKEN_SIZE_BYTES = 8 * 1024;
+  /** Off Zaisma, after Zaisma.setUpOffZaisma: { gameSlug, playerToken } for joins and requests to the game's own server. */
+  var offZaisma = null;
+
   /** An Error with a code, as the SDK's errors all have. */
   function codedError(code, message) {
     var error = new Error(message);
@@ -88,6 +99,36 @@
     return codedError("not_on_zaisma", message);
   }
 
+  /**
+   * Off Zaisma, the game's own server can't take a Zaisma pass: what to do instead, or null when it can go ahead
+   * (on Zaisma, or set up off it). serverUrl: the call's own server, which off Zaisma it needs.
+   */
+  function offZaismaRefusal(serverUrl, call) {
+    if (config.rooms) return null;
+    if (!serverUrl) return notOnZaisma("Zaisma's rooms serve games played on Zaisma; off Zaisma, give serverUrl, the address of your own game server, to " + call + ".");
+    if (!offZaisma) return notOnZaisma("Off Zaisma, call Zaisma.setUpOffZaisma({ gameSlug, playerToken }) first: your own server knows the player by the playerToken, and serverUrl points " + call + " at it.");
+    return null;
+  }
+
+  /**
+   * Set up a game played off Zaisma (zaisma.d.ts: Zaisma.setUpOffZaisma). On a Zaisma page it changes nothing,
+   * so the same code runs in both places; elsewhere it keeps the game's slug and its player's token for joins
+   * and requests to the game's own server. Called again, it replaces the token (a new sign-in, or signing out).
+   */
+  function setUpOffZaisma(setUpOptions) {
+    var refused = unknownOption(setUpOptions, SET_UP_OFF_ZAISMA_OPTIONS, "Zaisma.setUpOffZaisma");
+    if (refused) return Promise.reject(refused);
+    if (config.rooms) return Promise.resolve({ isOffZaisma: false });
+    setUpOptions = setUpOptions || {};
+    var gameSlug = setUpOptions.gameSlug;
+    if (typeof gameSlug !== "string" || !GAME_SLUG.test(gameSlug)) return Promise.reject(codedError("bad_game_slug", "gameSlug is your game's slug, as its Zaisma link names it: 1 to 40 lowercase letters, digits or hyphens, like \"my-game\"."));
+    var playerToken = setUpOptions.playerToken === undefined ? null : setUpOptions.playerToken;
+    var isToken = typeof playerToken === "string" && playerToken.length > 0 && new TextEncoder().encode(playerToken).length <= MAXIMUM_PLAYER_TOKEN_SIZE_BYTES;
+    if (playerToken !== null && !isToken) return Promise.reject(codedError("bad_player_token", "playerToken is the player's token for your own server, as text up to 8 KB (a Sign in with Zaisma ID token, or your game's own), or null for a guest."));
+    offZaisma = { gameSlug: gameSlug, playerToken: playerToken };
+    return Promise.resolve({ isOffZaisma: true });
+  }
+
   /** The error for options a call doesn't take, naming the ones it does, or null when they're all fine. */
   function unknownOption(given, valid, call) {
     if (given === undefined || given === null) return null;
@@ -435,6 +476,8 @@
     // What this connection uses now: "webtransport" once the fast lane opens, else "websocket".
     this.transport = "websocket";
     this._pass = setup.pass;
+    // Off Zaisma: the hello carries the playerToken Zaisma.setUpOffZaisma holds now, so a reconnect uses a refreshed one.
+    this._isOffZaisma = setup.isOffZaisma === true;
     this._made = { isListed: this.isListed, friendJoinsEnabled: setup.friendJoinsEnabled === false ? false : undefined, name: setup.name, labels: setup.labels };
     this._joinData = setup.joinData === undefined ? null : setup.joinData;
     this._serverUrl = setup.serverUrl;
@@ -653,7 +696,7 @@
   };
 
   // Codes that mean this room won't take the player, so joining fails instead of trying again.
-  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
+  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "bad_player_token", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
 
   /**
    * Whether a Zaisma room on another version (other_version) has the page reload the game at it: on the
@@ -685,7 +728,9 @@
       room.transport = isFastLane ? "webtransport" : "websocket";
       room._pingAtMs = room._pongAtMs = room._heardAtMs = Date.now();
       room._probeIntervalSec = null;
-      var hello = { type: "hello", protocolVersionNumber: PROTOCOL_VERSION_NUMBER, pass: room._pass, room: room._made, joinData: room._joinData, idleTimeoutSec: room._clientIdle.idleTimeoutSec, idleCheckEnabled: room._clientIdle.idleCheckEnabled };
+      var hello = { type: "hello", protocolVersionNumber: PROTOCOL_VERSION_NUMBER, room: room._made, joinData: room._joinData, idleTimeoutSec: room._clientIdle.idleTimeoutSec, idleCheckEnabled: room._clientIdle.idleCheckEnabled };
+      if (room._isOffZaisma) hello.playerToken = offZaisma.playerToken;
+      else hello.pass = room._pass;
       // quickJoin's first try at a room: rather another room than one with someone this player blocked.
       if (room._avoidsBlockedPlayers) hello.avoidBlockedPlayers = true;
       // Any quickJoin: Zaisma learns the game joins players by itself, for its Rooms tab.
@@ -1527,7 +1572,9 @@
 
   function connect(roomCode, joinOptions, isRetry) {
     var serverUrl = joinOptions.serverUrl ? String(joinOptions.serverUrl).replace(/\/+$/, "") : null;
-    if (!serverUrl && !config.rooms) return Promise.reject(notOnZaisma("Player passes come from Zaisma, so rooms work only in games hosted on Zaisma, in Zaisma rooms or on your own server (serverUrl)."));
+    var offRefusal = offZaismaRefusal(serverUrl, "Zaisma.joinRoom");
+    if (offRefusal) return Promise.reject(offRefusal);
+    var isOffZaisma = !config.rooms;
     var idleTimeoutSec = joinOptions.idleTimeoutSec;
     if (idleTimeoutSec !== undefined && !(typeof idleTimeoutSec === "number" && idleTimeoutSec >= MINIMUM_IDLE_TIMEOUT_SEC && idleTimeoutSec <= MAXIMUM_IDLE_TIMEOUT_SEC)) return Promise.reject(codedError("bad_idle_timeout", "idleTimeoutSec runs from " + MINIMUM_IDLE_TIMEOUT_SEC + " to " + MAXIMUM_IDLE_TIMEOUT_SEC + "."));
     if (serverUrl && !SERVER_URL.test(serverUrl)) return Promise.reject(codedError("bad_server_url", "serverUrl takes a full address starting with wss://, ws://, https:// or http://, like \"wss://play.example.com\"."));
@@ -1539,12 +1586,14 @@
       : serverUrl
         ? Promise.resolve(randomRoomCode())
         : post("/v1/rooms", { gameSlug: config.game }).then(function (answer) { return answer.roomCode; });
-    return Promise.all([roomCodeReady, getPass()]).then(function (ready) {
+    // Off Zaisma there's no pass: the hello carries the playerToken instead.
+    return Promise.all([roomCodeReady, isOffZaisma ? null : getPass()]).then(function (ready) {
       var base = (serverUrl || config.rooms).replace(/^http/, "ws");
-      var path = "/v1/rooms/" + config.game + "/" + ready[0];
+      var path = "/v1/rooms/" + (isOffZaisma ? offZaisma.gameSlug : config.game) + "/" + ready[0];
       var room = new Room({
         roomCode: ready[0],
-        pass: ready[1].pass,
+        pass: isOffZaisma ? null : ready[1].pass,
+        isOffZaisma: isOffZaisma,
         url: base + path,
         // The fast lane reaches only the game's own secure servers: Zaisma's rooms take the WebSocket, whatever transport says.
         fastLaneUrl: joinOptions.transport === "webtransport" && serverUrl && OWN_SERVER_URL.test(serverUrl) ? serverUrl.replace(/^wss:/, "https:") + path : null,
@@ -1566,8 +1615,8 @@
         room._ready = { resolve: resolve, reject: reject };
         room._connect();
       }).catch(function (error) {
-        // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more.
-        if (error.code !== "bad_pass" || isRetry) throw error;
+        // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more. Off Zaisma, only the game can get a new token.
+        if (error.code !== "bad_pass" || isRetry || isOffZaisma) throw error;
         try { sessionStorage.removeItem(passKey); } catch (storageError) { /* fine */ }
         return connect(room.roomCode, joinOptions, true);
       });
@@ -1770,13 +1819,15 @@
 
   /**
    * A request to the game's own game server, its onRequest, outside any room: what it answered
-   * (zaisma.d.ts: Zaisma.server.request). The player's pass goes with it, so the server knows who's asking.
+   * (zaisma.d.ts: Zaisma.server.request). The player's pass goes with it, so the server knows who's asking;
+   * off Zaisma, the playerToken Zaisma.setUpOffZaisma holds.
    */
   function serverRequest(request, requestOptions, isRetry) {
     var refused = unknownOption(requestOptions, REQUEST_OPTIONS, "Zaisma.server.request");
     if (refused) return Promise.reject(refused);
     var serverUrl = requestOptions && requestOptions.serverUrl ? String(requestOptions.serverUrl).replace(/\/+$/, "") : null;
-    if (!serverUrl && !config.rooms) return Promise.reject(notOnZaisma("Player passes come from Zaisma, so Zaisma.server.request works only in games hosted on Zaisma, to Zaisma's servers or to your own (serverUrl)."));
+    var offRefusal = offZaismaRefusal(serverUrl, "Zaisma.server.request");
+    if (offRefusal) return Promise.reject(offRefusal);
     if (serverUrl && !SERVER_URL.test(serverUrl)) return Promise.reject(codedError("bad_server_url", "serverUrl takes a full address starting with https://, http://, wss:// or ws://, like \"https://play.example.com\"."));
     var requestText;
     try {
@@ -1787,13 +1838,17 @@
     if (requestText === undefined) return Promise.reject(codedError("bad_request", "A request is plain JSON: numbers, text, true or false, null, lists and plain objects, like { type: \"buy\", itemId: \"sword\" }."));
     if (new TextEncoder().encode(requestText).length > MAXIMUM_REQUEST_SIZE_BYTES) return Promise.reject(codedError("too_big", "Requests are up to 16 KB as JSON."));
     var base = (serverUrl || config.rooms).replace(/^ws/, "http");
-    return getPass().then(function (mine) {
-      return fetch(base + "/v1/requests/" + config.game, { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify({ pass: mine.pass, request: JSON.parse(requestText) }) }).then(answered, requestFailed);
+    var isOffZaisma = !config.rooms;
+    // Off Zaisma there's no pass: the playerToken goes in its place.
+    var sender = isOffZaisma ? Promise.resolve({ playerToken: offZaisma.playerToken }) : getPass().then(function (mine) { return { pass: mine.pass }; });
+    return sender.then(function (who) {
+      who.request = JSON.parse(requestText);
+      return fetch(base + "/v1/requests/" + (isOffZaisma ? offZaisma.gameSlug : config.game), { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify(who) }).then(answered, requestFailed);
     }).then(function (answer) {
       return answer.answer;
     }, function (error) {
-      // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more.
-      if (error.code !== "bad_pass" || isRetry) throw error;
+      // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more. Off Zaisma, only the game can get a new token.
+      if (error.code !== "bad_pass" || isRetry || isOffZaisma) throw error;
       try { sessionStorage.removeItem(passKey); } catch (storageError) { /* fine */ }
       return serverRequest(request, requestOptions, true);
     });
@@ -2698,5 +2753,5 @@
   });
 
   var friends = { list: listFriends, setRoom: setOwnRoom, sendRequest: sendFriendRequest };
-  window.Zaisma = { sdkVersionNumber: 1, gameSlug: config.game || null, player: player, joinRoom: joinRoom, rooms: rooms, server: server, invite: invite, checkChat: checkChat, openPlayersPanel: openPlayersPanel, links: links, items: items, friends: friends, saves: saves, versions: versions, page: zaismaPage };
+  window.Zaisma = { sdkVersionNumber: 1, gameSlug: config.game || null, player: player, setUpOffZaisma: setUpOffZaisma, joinRoom: joinRoom, rooms: rooms, server: server, invite: invite, checkChat: checkChat, openPlayersPanel: openPlayersPanel, links: links, items: items, friends: friends, saves: saves, versions: versions, page: zaismaPage };
 })();

package/src/chat.d.ts

@@ -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).
  */
@@ -36,10 +41,10 @@ export interface ChatCheck {
 export interface ChatCheckOptions {
     /** The message. */
     text: string;
-    /** The sender's player pass, the signed token as your server received it. */
-    senderPass: string;
-    /** The passes of everyone it would reach, up to 50. */
-    receiverPasses: string[];
+    /** The sender's player pass, the signed token as your server received it; null for a player from outside Zaisma. */
+    senderPass: string | null;
+    /** The passes of everyone it would reach, up to 50; null for each player from outside Zaisma. */
+    receiverPasses: (string | null)[];
     /** Check chat between adults too, as for under-18s; each message Zaisma's AI looks at counts on your hosting meter. False by default. */
     isAdultFilterEnabled?: boolean;
 }