@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/HeadlessRuntime.js

@@ -0,0 +1,380 @@
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import vm from "node:vm";
+import { getLogger } from "./GameServerLogger.js";
+/** The loaded runtime, or null before loadToolkitRuntime. */
+let loadedRuntime = null;
+/**
+ * Loads the browser runtime into Node (D25): babylonjs, its loaders and GUI, then the toolkit UMD bundle, which publishes
+ * TOOLKIT (networking included) on globalThis. The session logic and protocol the server runs are therefore the same code as the
+ * browser's. Loads once; later calls return the same globals.
+ * @returns The BABYLON and TOOLKIT namespaces.
+ */
+export async function loadToolkitRuntime() {
+    if (loadedRuntime != null)
+        return loadedRuntime;
+    const requireModule = createRequire(import.meta.url);
+    const globalScope = globalThis;
+    const babylon = requireModule("babylonjs");
+    globalScope.BABYLON = babylon;
+    requireModule("babylonjs-loaders");
+    babylon.GUI = requireModule("babylonjs-gui");
+    requireModule("babylonjs-toolkit");
+    if (globalScope.TOOLKIT == null)
+        throw new Error("babylonjs-toolkit did not publish TOOLKIT on globalThis");
+    if (typeof globalScope.TOOLKIT.NETWORK_PROTOCOL_VERSION !== "number")
+        throw new Error(olderRuntimeMessage(requireModule));
+    loadedRuntime = { BABYLON: babylon, TOOLKIT: globalScope.TOOLKIT };
+    return loadedRuntime;
+}
+/**
+ * The startup error of a runtime that predates the network protocol version (§Error policy).
+ * @param requireModule Resolves packages the way the server does.
+ * @returns The message, naming the installed babylonjs-toolkit version.
+ */
+function olderRuntimeMessage(requireModule) {
+    const runtimePackage = requireModule("babylonjs-toolkit/package.json");
+    return "babylonjs-toolkit " + (runtimePackage.version ?? "(unknown version)") + " is older than this server needs; install the version this server was released with";
+}
+/**
+ * The loaded runtime, for code that runs after createGameServer has loaded it (rooms).
+ * @returns The runtime globals.
+ * @throws Error when loadToolkitRuntime has not completed.
+ */
+export function getToolkitRuntime() {
+    if (loadedRuntime == null)
+        throw new Error("The toolkit runtime is not loaded: await loadToolkitRuntime() first");
+    return loadedRuntime;
+}
+/** The SceneLoader entry points the toolkit calls (SceneManager, CoreFramework, NetworkSceneManager), with their argument positions. */
+const SCENE_LOADER_ENTRY_POINTS = [
+    { name: "LoadAsync", rootUrlIndex: 0, pluginExtensionIndex: 4, nameIndex: 5, onErrorIndex: -1 },
+    { name: "AppendAsync", rootUrlIndex: 0, pluginExtensionIndex: 4, nameIndex: 5, onErrorIndex: -1 },
+    { name: "LoadAssetContainerAsync", rootUrlIndex: 0, pluginExtensionIndex: 4, nameIndex: 5, onErrorIndex: -1 },
+    { name: "ImportMeshAsync", rootUrlIndex: 1, pluginExtensionIndex: 5, nameIndex: 6, onErrorIndex: -1 },
+    { name: "LoadAssetContainer", rootUrlIndex: 0, pluginExtensionIndex: 6, nameIndex: 7, onErrorIndex: 5 },
+    { name: "ImportMesh", rootUrlIndex: 1, pluginExtensionIndex: 7, nameIndex: 8, onErrorIndex: 6 }
+];
+/** Prefix of a data URL. */
+const DATA_URL_PREFIX = "data:";
+/** Prefix of a binary file as a data URL. */
+const BINARY_DATA_URL_PREFIX = "data:application/octet-stream;base64,";
+/** File extension of a binary glTF. */
+const BINARY_GLTF_EXTENSION = ".glb";
+/** Shortest time between two log lines about failed dedicated frames, in milliseconds. */
+const FRAME_FAILURE_LOG_INTERVAL_MS = 10000;
+/** Name and position of the camera added to a scene without one, as engine.html adds it (A19). */
+const DEFAULT_CAMERA_NAME = "Default Camera";
+const DEFAULT_CAMERA_HEIGHT = 5;
+const DEFAULT_CAMERA_DISTANCE = -10;
+/**
+ * Texture units a headless engine reports. A NullEngine draws nothing, so the toolkit's per-material sampler budget (16 on
+ * the NullEngine's invented limits) would only warn that materials "will not render".
+ */
+const HEADLESS_TEXTURE_UNITS = 1024;
+/** Runtime options of a headless scene (A18): no device pixel ratio, no input, no page loading screen, no bundle. */
+const HEADLESS_RUNTIME_OPTIONS = { hardwareScalingLevel: 1, trackDevicePixelRatio: false, enableUserInput: false, showDefaultLoadingScreen: false, loadProjectScriptBundle: false };
+/** Prefix of a file URL, which the fetch helpers read from disk. */
+const FILE_URL_PREFIX = "file:";
+/** Scene file URLs the scene loader adapts (HTTP and local folders, D19). */
+const LOADABLE_SCENE_URL_PATTERN = /^(https?|file):/i;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/**
+ * URL prefixes the fetch helpers may load (D19), or null to allow every URL. It stays null when HeadlessRuntime is used on
+ * its own; createGameServer always sets it (to the dedicated scene registry's prefixes, possibly none) and close resets it.
+ */
+let allowedUrlPrefixes = null;
+/** Lower-cased file names of the scripts the Node script loader has run (the toolkit's bundle cache key). */
+const loadedScriptNames = new Set();
+/** Script loads in flight, by cache key, so concurrent loads of one bundle run it once. */
+const pendingScriptLoads = new Map();
+/** True once the Node loaders replaced Babylon's DOM-based ones. */
+let nodeLoadersInstalled = false;
+/** True once Havok is ready on globalThis. */
+let havokInstalled = false;
+/**
+ * Adds URL prefixes to the allow-list of the fetch helpers (D19). The first call turns the allow-list on: from then on
+ * only data: URLs and URLs under an allowed prefix load.
+ * @param prefixes The URL prefixes (scene roots and project scripts); none turns the allow-list on with only data: URLs.
+ */
+export function allowScriptUrlPrefixes(prefixes) {
+    const allowed = allowedUrlPrefixes ?? [];
+    for (const prefix of prefixes) {
+        if (!allowed.includes(prefix))
+            allowed.push(prefix);
+    }
+    allowedUrlPrefixes = allowed;
+}
+/**
+ * Turns the allow-list off again (every URL allowed), as before any game server ran. createGameServer's close calls it.
+ */
+export function resetScriptUrlAllowList() {
+    allowedUrlPrefixes = null;
+}
+/**
+ * Whether the fetch helpers may load a URL (D19).
+ * @param url The URL.
+ * @returns True for a data: URL, for any URL while the allow-list is off, else when the URL starts with an allowed prefix.
+ */
+export function isUrlAllowed(url) {
+    if (url.startsWith(DATA_URL_PREFIX) || allowedUrlPrefixes == null)
+        return true;
+    return allowedUrlPrefixes.some((prefix) => url.startsWith(prefix));
+}
+/**
+ * The cache key of a script URL: its lower-cased file name, as the toolkit keys its project bundles (CanvasTools.ts).
+ * @param scriptUrl The script URL.
+ * @returns The key.
+ */
+export function scriptCacheKey(scriptUrl) {
+    const withoutQuery = scriptUrl.split(/[?#]/)[0];
+    return withoutQuery.substring(withoutQuery.lastIndexOf("/") + 1).toLowerCase();
+}
+/**
+ * Loads a script in Node, as Babylon's LoadScriptAsync does in a page (T13 step 2): fetches it and runs it in this context,
+ * once per file name; a file name already loaded resolves at once.
+ * @param scriptUrl The script URL.
+ * @returns Resolves once it ran.
+ * @throws Error when the server answers with an error status (the toolkit then warns that the bundle was not found), or
+ *     when the URL is not on the dedicated allow-list (D19).
+ */
+export async function loadNodeScriptAsync(scriptUrl) {
+    const cacheKey = scriptCacheKey(scriptUrl);
+    if (loadedScriptNames.has(cacheKey))
+        return;
+    const pending = pendingScriptLoads.get(cacheKey);
+    if (pending != null)
+        return pending;
+    const load = fetchAndRunScript(scriptUrl, cacheKey);
+    pendingScriptLoads.set(cacheKey, load);
+    try {
+        await load;
+    }
+    finally {
+        pendingScriptLoads.delete(cacheKey);
+    }
+}
+/**
+ * Fetches a script and runs it in this context.
+ * @param scriptUrl The script URL.
+ * @param cacheKey Its cache key, recorded once it ran.
+ * @throws Error when the URL is not allowed, or answers with an error status.
+ */
+async function fetchAndRunScript(scriptUrl, cacheKey) {
+    const source = await fetchText(scriptUrl);
+    vm.runInThisContext(source, { filename: scriptUrl });
+    loadedScriptNames.add(cacheKey);
+}
+/**
+ * Replaces Babylon's DOM-based loaders with Node ones, once (T13 step 2): BABYLON.Tools.LoadScriptAsync / LoadScript use
+ * the Node script loader, so the toolkit's project bundle auto-load works unchanged; BABYLON.SceneLoader's entry points
+ * fetch the scene file over HTTP and hand it over as data, and the glTF loader fetches its buffers the same way and loads
+ * no materials (no textures headless). Babylon's own versions use a script element and XMLHttpRequest, which Node lacks.
+ * @param babylon The BABYLON namespace.
+ */
+export function installNodeLoaders(babylon) {
+    if (nodeLoadersInstalled)
+        return;
+    nodeLoadersInstalled = true;
+    babylon.Tools.LoadScriptAsync = (scriptUrl) => loadNodeScriptAsync(scriptUrl);
+    babylon.Tools.LoadScript = (scriptUrl, onSuccess, onError) => {
+        loadNodeScriptAsync(scriptUrl).then(() => onSuccess?.(), (error) => onError?.(String(error), error));
+    };
+    babylon.SceneLoader.OnPluginActivatedObservable.add((plugin) => {
+        if (plugin == null || plugin.name !== "gltf")
+            return;
+        plugin.skipMaterials = true;
+        plugin.preprocessUrlAsync = (url) => fetchAsDataUrl(url);
+    });
+    for (const entryPoint of SCENE_LOADER_ENTRY_POINTS)
+        adaptSceneLoaderEntryPoint(babylon.SceneLoader, entryPoint);
+}
+/**
+ * Wraps one SceneLoader entry point: an HTTP scene file is fetched first and passed as data, with its extension (which
+ * picks the loader plugin) and its file name (which the toolkit records for the scene).
+ * @param sceneLoader BABYLON.SceneLoader.
+ * @param entryPoint The entry point and its argument positions.
+ */
+function adaptSceneLoaderEntryPoint(sceneLoader, entryPoint) {
+    const original = sceneLoader[entryPoint.name];
+    if (typeof original !== "function")
+        return;
+    const callOriginal = (args) => original.apply(sceneLoader, args);
+    if (entryPoint.onErrorIndex < 0) {
+        sceneLoader[entryPoint.name] = async (...args) => callOriginal(await withSceneData(args, entryPoint));
+        return;
+    }
+    sceneLoader[entryPoint.name] = (...args) => {
+        withSceneData(args, entryPoint).then((dataArgs) => callOriginal(dataArgs), (error) => {
+            const onError = args[entryPoint.onErrorIndex];
+            if (typeof onError === "function")
+                onError(null, String(error), error);
+            else
+                getLogger().error("headless scene load failed", { error: String(error) });
+        });
+        return null;
+    };
+}
+/**
+ * The arguments of a scene loader call with an HTTP or file:// scene file replaced by its data.
+ * @param args The call's arguments.
+ * @param entryPoint The entry point's argument positions.
+ * @returns The arguments to call the original entry point with.
+ */
+async function withSceneData(args, entryPoint) {
+    const rootUrl = args[entryPoint.rootUrlIndex];
+    const sceneFile = args[entryPoint.rootUrlIndex + 1];
+    if (typeof rootUrl !== "string" || typeof sceneFile !== "string" || sceneFile.startsWith(DATA_URL_PREFIX))
+        return args;
+    const url = rootUrl + sceneFile;
+    if (!LOADABLE_SCENE_URL_PATTERN.test(url))
+        return args;
+    const dataArgs = args.slice();
+    const extension = fileExtension(sceneFile);
+    dataArgs[entryPoint.rootUrlIndex + 1] = (extension === BINARY_GLTF_EXTENSION) ? await fetchAsDataUrl(url) : DATA_URL_PREFIX + await fetchText(url);
+    if (dataArgs[entryPoint.pluginExtensionIndex] == null)
+        dataArgs[entryPoint.pluginExtensionIndex] = extension;
+    if (dataArgs[entryPoint.nameIndex] == null || dataArgs[entryPoint.nameIndex] === "")
+        dataArgs[entryPoint.nameIndex] = sceneFile;
+    return dataArgs;
+}
+/**
+ * The lower-cased extension of a file name, without its query.
+ * @param fileName The file name.
+ * @returns The extension with its dot (".gltf"), or "".
+ */
+function fileExtension(fileName) {
+    const withoutQuery = fileName.split(/[?#]/)[0];
+    const dotIndex = withoutQuery.lastIndexOf(".");
+    return (dotIndex >= 0) ? withoutQuery.substring(dotIndex).toLowerCase() : "";
+}
+/**
+ * Fetches a file's text: over HTTP, or from disk for a file:// URL.
+ * @param url The URL.
+ * @returns The text.
+ * @throws Error when the URL is not on the dedicated allow-list, or on an error status.
+ */
+async function fetchText(url) {
+    const bytes = await fetchBytes(url);
+    return bytes.toString("utf8");
+}
+/**
+ * Fetches a file as a base64 data URL, which Babylon loads without a request; a data URL passes through.
+ * @param url The URL.
+ * @returns The data URL.
+ * @throws Error when the URL is not on the dedicated allow-list, or on an error status.
+ */
+async function fetchAsDataUrl(url) {
+    if (url.startsWith(DATA_URL_PREFIX))
+        return url;
+    const bytes = await fetchBytes(url);
+    return BINARY_DATA_URL_PREFIX + bytes.toString("base64");
+}
+/**
+ * Fetches a file's bytes, after checking the allow-list (D19): over HTTP, or from disk for a file:// URL.
+ * @param url The URL.
+ * @returns The bytes.
+ * @throws Error("URL is not on the dedicated allow-list: <url>") without making a request, or on an error status.
+ */
+async function fetchBytes(url) {
+    if (!isUrlAllowed(url))
+        throw new Error("URL is not on the dedicated allow-list: " + url);
+    if (url.startsWith(FILE_URL_PREFIX))
+        return readFile(fileURLToPath(url.split(/[?#]/)[0]));
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(url + " answered " + response.status + " " + response.statusText);
+    return Buffer.from(await response.arrayBuffer());
+}
+/**
+ * Makes Havok available the way the toolkit's physics setup expects (A18): globalThis.HavokPhysics() resolves the Havok
+ * module (its wasm read from the package), and globalThis.HK holds it, as the browser page sets it before loading a scene.
+ */
+async function installHavok() {
+    if (havokInstalled)
+        return;
+    const requireModule = createRequire(import.meta.url);
+    const havokFactory = requireModule("@babylonjs/havok");
+    const wasmBinary = await readFile(requireModule.resolve("@babylonjs/havok/lib/umd/HavokPhysics.wasm"));
+    const globalScope = globalThis;
+    const havok = await havokFactory({ wasmBinary: wasmBinary });
+    globalScope.HavokPhysics = () => Promise.resolve(havok);
+    globalScope.HK = havok;
+    havokInstalled = true;
+}
+/**
+ * Loads an exported toolkit scene headless (T13 step 2): the same .gltf the browser loads, fetched over HTTP, on a
+ * NullEngine with Havok, the toolkit runtime initialised without a page (A18) and no materials or textures; the scene's
+ * project script bundle auto-loads through the Node script loader. As engine.html does, a scene without a camera gets a
+ * default one and the render loop starts; it resolves once the toolkit has created the scene's components and the scene
+ * is ready (TOOLKIT.SceneManager.WhenSceneReady).
+ * @param sceneRootUrl The folder URL of the scene: http(s):// (for example "http://localhost:8877/scenes/") or file://.
+ * @param sceneFile The scene file (for example "networktestbed.gltf").
+ * @param onFrameRendered Receives each frame's duration in seconds (the dedicated frame metrics, D16).
+ * @returns The engine and the ready, rendering scene.
+ * @throws Error when the toolkit does not report the scene ready.
+ */
+export async function loadHeadlessScene(sceneRootUrl, sceneFile, onFrameRendered) {
+    const runtime = await loadToolkitRuntime();
+    const babylon = runtime.BABYLON;
+    const toolkit = runtime.TOOLKIT;
+    installNodeLoaders(babylon);
+    await installHavok();
+    const engine = new babylon.NullEngine();
+    engine.getCaps().maxTexturesImageUnits = HEADLESS_TEXTURE_UNITS;
+    await toolkit.SceneManager.InitializeRuntime(engine, HEADLESS_RUNTIME_OPTIONS);
+    const loadScene = babylon.SceneLoader["LoadAsync"];
+    const scene = await loadScene(sceneRootUrl, sceneFile, engine);
+    await scene.whenReadyAsync();
+    // As engine.html does: a scene renders only with a camera.
+    if (scene.cameras.length === 0)
+        new babylon.FreeCamera(DEFAULT_CAMERA_NAME, new babylon.Vector3(0, DEFAULT_CAMERA_HEIGHT, DEFAULT_CAMERA_DISTANCE), scene);
+    const reportFrameFailure = createFrameFailureReporter();
+    engine.runRenderLoop(() => renderTimed(scene, onFrameRendered, reportFrameFailure));
+    const isReady = await toolkit.SceneManager.WhenSceneReady(scene);
+    if (!isReady) {
+        engine.dispose();
+        throw new Error("[GameServer] the headless scene " + sceneRootUrl + sceneFile + " did not get ready");
+    }
+    return { engine: engine, scene: scene };
+}
+/**
+ * Renders one frame, reporting how long it took when asked. A frame that throws stays inside this function: the render
+ * loop runs outside every request, so the error would otherwise end the process, and with it every session on it. A
+ * client can cause one, because the runner decodes what clients send during the frame. The runner drops a frame before
+ * decoding it, so the next render carries on.
+ * @param scene The scene.
+ * @param onFrameRendered Receives the frame's duration in seconds, or undefined.
+ * @param reportFailure Told about a frame that threw.
+ */
+function renderTimed(scene, onFrameRendered, reportFailure) {
+    const startedAt = performance.now();
+    try {
+        scene.render();
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    onFrameRendered?.((performance.now() - startedAt) / MILLISECONDS_PER_SECOND);
+}
+/**
+ * Makes the function that logs failed frames. A scene script that throws fails every frame, so it logs at most once per
+ * FRAME_FAILURE_LOG_INTERVAL_MS and counts the rest.
+ * @returns The reporter of one scene.
+ */
+function createFrameFailureReporter() {
+    let lastLoggedAt = Number.NEGATIVE_INFINITY;
+    let failuresSinceLog = 0;
+    return (error) => {
+        failuresSinceLog += 1;
+        const now = performance.now();
+        if (now - lastLoggedAt < FRAME_FAILURE_LOG_INTERVAL_MS)
+            return;
+        const failure = (error instanceof Error) ? (error.stack ?? error.message) : String(error);
+        getLogger().error("a dedicated frame failed", { error: failure, failedFrames: failuresSinceLog });
+        lastLoggedAt = now;
+        failuresSinceLog = 0;
+    };
+}

package/lib/JoinGate.d.ts

@@ -0,0 +1,34 @@
+import { type AuthContext } from "colyseus";
+import { type AuthIdentity } from "./Authentication.js";
+import { type FusionConnectRequest } from "./HeadlessRuntime.js";
+/** What the gate hands Colyseus for `client.auth`: who the player is and where it connects from. */
+export interface JoinGateResult {
+    /** The verified identity, or null when auth is off. */
+    identity: AuthIdentity | null;
+    /** The client's address (D11). */
+    clientAddress: string;
+}
+/** Which room a join is for: a session, or the lobby (which skips the session-only checks). */
+export type JoinKind = "session" | "lobby";
+/** The client address used when the request carries none (D11). */
+export declare const UNKNOWN_CLIENT_ADDRESS: string;
+/**
+ * The one gate every join passes at matchmaking (D10), called by the static onAuth of SessionRoom ("session") and
+ * GameServerLobbyRoom ("lobby"). In order: draining, maintenance (sessions), origin, address bans, per-address rate,
+ * then for sessions the protocol version, session name and on-demand dedicated scene, then the token verifier when
+ * auth is on, and finally the checks that need the verified identity (user bans, kick blocks, maintenance allow lists).
+ * @param token The bearer token the client sent, if any.
+ * @param options The join options (a session's NetworkConnectRequest; the lobby's are empty).
+ * @param context Colyseus' matchmaking context: headers and the client address.
+ * @param kind Which room the join is for.
+ * @returns The identity and client address, which Colyseus stores as client.auth.
+ * @throws ServerError(status, "<Reason>: <detail>") when the join is refused.
+ */
+export declare function authorizeJoin(token: string | undefined, options: Partial<FusionConnectRequest> | undefined, context: AuthContext, kind: JoinKind): Promise<JoinGateResult>;
+/**
+ * The dedicated scene a Client-mode join asks the server to start on demand (D19): the NETWORK_DEDICATED_SCENE_PROPERTY
+ * session property, when it is non-empty text.
+ * @param request The join options.
+ * @returns The scene name, or null when the join names none (or is not a Client join).
+ */
+export declare function requestedDedicatedScene(request: Partial<FusionConnectRequest>): string | null;

package/lib/JoinGate.js

@@ -0,0 +1,221 @@
+import { ErrorCode, ServerError } from "colyseus";
+import { isOriginAllowed, sessionNameProblem } from "./AbuseLimits.js";
+import { AuthRefusal } from "./Authentication.js";
+import { getLogger } from "./GameServerLogger.js";
+import { getGameServerState } from "./GameServerState.js";
+import { getToolkitRuntime } from "./HeadlessRuntime.js";
+import { normalizeAddress } from "./NetworkAddresses.js";
+import { needsVerification, verifyPlayerToken } from "./PlayerTokens.js";
+import { banRefusalDetail } from "./admin/BanList.js";
+/** The client address used when the request carries none (D11). */
+export const UNKNOWN_CLIENT_ADDRESS = "unknown";
+/** HTTP status of a join refused because the server is draining or full. */
+const SERVICE_UNAVAILABLE_STATUS = 503;
+/** HTTP status of a join from an origin that is not allowed. */
+const FORBIDDEN_STATUS = 403;
+/** HTTP status of a join over the per-address rate. */
+const TOO_MANY_REQUESTS_STATUS = 429;
+/** HTTP status of a Client join naming a dedicated scene the server cannot start on demand (D6). */
+const NOT_FOUND_STATUS = 404;
+/** HTTP status of a join with a wrong protocol version or a bad session name. */
+const BAD_REQUEST_STATUS = 400;
+/**
+ * The one gate every join passes at matchmaking (D10), called by the static onAuth of SessionRoom ("session") and
+ * GameServerLobbyRoom ("lobby"). In order: draining, maintenance (sessions), origin, address bans, per-address rate,
+ * then for sessions the protocol version, session name and on-demand dedicated scene, then the token verifier when
+ * auth is on, and finally the checks that need the verified identity (user bans, kick blocks, maintenance allow lists).
+ * @param token The bearer token the client sent, if any.
+ * @param options The join options (a session's NetworkConnectRequest; the lobby's are empty).
+ * @param context Colyseus' matchmaking context: headers and the client address.
+ * @param kind Which room the join is for.
+ * @returns The identity and client address, which Colyseus stores as client.auth.
+ * @throws ServerError(status, "<Reason>: <detail>") when the join is refused.
+ */
+export async function authorizeJoin(token, options, context, kind) {
+    const state = getGameServerState();
+    const clientAddress = context.ip ?? UNKNOWN_CLIENT_ADDRESS;
+    const origin = context.headers.get("origin");
+    const request = options ?? {};
+    const refusal = checkAdmission(state, clientAddress, origin, request, kind);
+    if (refusal != null)
+        refuse(state, refusal, clientAddress, origin, request);
+    const identity = await verifyToken(state, token ?? "", kind, request, clientAddress, origin);
+    const lateRefusal = await checkAuthenticated(state, clientAddress, identity, kind, request);
+    if (lateRefusal != null)
+        refuse(state, lateRefusal, clientAddress, origin, request);
+    return { identity: identity, clientAddress: clientAddress };
+}
+/**
+ * The checks that need the verified identity (game-server-admin-console D12, D15, R19, R20): a user-id ban, then for
+ * session joins a kick block of the user id or the address, then maintenance with a user-id allow list (the join
+ * passes only when its address or its user id is allowed).
+ * @param state The server state.
+ * @param clientAddress The client's address.
+ * @param identity The verified identity, or null when auth is off.
+ * @param kind Which room the join is for.
+ * @param request The join options.
+ * @returns The refusal, or null when the join may go on.
+ */
+async function checkAuthenticated(state, clientAddress, identity, kind, request) {
+    const userId = identity?.userId ?? null;
+    const userBan = (userId != null) ? state.banList?.userBan(userId) ?? null : null;
+    if (userBan != null)
+        return banRefusal(userBan);
+    if (kind !== "session")
+        return null;
+    if (await state.kickBlocks.isBlocked(request.sessionName ?? "", userId, clientAddress)) {
+        return { status: FORBIDDEN_STATUS, reasonName: "ConnectionRefused", detail: "you were removed from this session" };
+    }
+    const maintenance = state.maintenance;
+    if (maintenance == null || isMaintenanceAddress(maintenance, clientAddress))
+        return null;
+    if (userId != null && maintenance.allowUserIds.includes(userId))
+        return null;
+    return maintenanceRefusal(maintenance);
+}
+/**
+ * The refusal of a banned joiner (D15): 403 ConnectionRefused with the ban's end time.
+ * @param record The ban.
+ * @returns The refusal.
+ */
+function banRefusal(record) {
+    return { status: FORBIDDEN_STATUS, reasonName: "ConnectionRefused", detail: banRefusalDetail(record) };
+}
+/**
+ * Whether maintenance still admits an address (its allowAddresses, compared after normalizing IPv4-mapped forms).
+ * @param maintenance The maintenance in force.
+ * @param clientAddress The client's address.
+ * @returns True when the address is allowed.
+ */
+function isMaintenanceAddress(maintenance, clientAddress) {
+    const normalized = normalizeAddress(clientAddress);
+    return maintenance.allowAddresses.some((allowed) => normalizeAddress(allowed) === normalized);
+}
+/**
+ * The refusal of a session join during maintenance (D14): 503 GameClosed with the maintenance message.
+ * @param maintenance The maintenance in force.
+ * @returns The refusal.
+ */
+function maintenanceRefusal(maintenance) {
+    return { status: SERVICE_UNAVAILABLE_STATUS, reasonName: "GameClosed", detail: maintenance.message };
+}
+/**
+ * The checks before authentication (D10 steps 1–6).
+ * @param state The server state.
+ * @param clientAddress The client's address.
+ * @param origin The request's Origin, or null.
+ * @param request The join options.
+ * @param kind Which room the join is for.
+ * @returns The first refusal, or null when the join may go on to authentication.
+ */
+function checkAdmission(state, clientAddress, origin, request, kind) {
+    if (state.draining)
+        return { status: SERVICE_UNAVAILABLE_STATUS, reasonName: "GameClosed", detail: "the server is shutting down" };
+    // Maintenance refuses here only when no user id could be allowed later; otherwise checkAuthenticated decides (R20).
+    const maintenance = state.maintenance;
+    if (kind === "session" && maintenance != null && maintenance.allowUserIds.length === 0 && !isMaintenanceAddress(maintenance, clientAddress))
+        return maintenanceRefusal(maintenance);
+    if (!isOriginAllowed(origin, state.config.limits))
+        return { status: FORBIDDEN_STATUS, reasonName: "ConnectionRefused", detail: "the origin " + (origin ?? "(none)") + " is not allowed" };
+    const addressBan = state.banList?.addressBan(clientAddress) ?? null;
+    if (addressBan != null)
+        return banRefusal(addressBan);
+    if (!state.rateLimiter.tryConsume(clientAddress))
+        return { status: TOO_MANY_REQUESTS_STATUS, reasonName: "ConnectionRefused", detail: "too many join requests from this address; try again in a minute" };
+    if (kind === "lobby")
+        return null;
+    const versionDetail = protocolVersionProblem(request.protocolVersion);
+    if (versionDetail != null)
+        return { status: BAD_REQUEST_STATUS, reasonName: "IncompatibleConfiguration", detail: versionDetail };
+    const nameDetail = sessionNameProblem(request.sessionName ?? "", state.config.limits);
+    if (nameDetail != null)
+        return { status: BAD_REQUEST_STATUS, reasonName: "InvalidArguments", detail: nameDetail };
+    const sceneName = requestedDedicatedScene(request);
+    if (sceneName != null && state.registry.find(sceneName)?.onDemand !== true)
+        return { status: NOT_FOUND_STATUS, reasonName: "GameNotFound", detail: "no on-demand dedicated scene named " + sceneName };
+    return null;
+}
+/**
+ * The dedicated scene a Client-mode join asks the server to start on demand (D19): the NETWORK_DEDICATED_SCENE_PROPERTY
+ * session property, when it is non-empty text.
+ * @param request The join options.
+ * @returns The scene name, or null when the join names none (or is not a Client join).
+ */
+export function requestedDedicatedScene(request) {
+    const toolkit = getToolkitRuntime().TOOLKIT;
+    if (request.gameMode !== toolkit.GameMode.Client)
+        return null;
+    const sceneName = request.sessionProperties?.[toolkit.NETWORK_DEDICATED_SCENE_PROPERTY];
+    return (typeof sceneName === "string" && sceneName !== "") ? sceneName : null;
+}
+/**
+ * Compares the client's network protocol version with the server's (D5); a missing version counts as 0.
+ * @param clientVersion The version the join sent, if any.
+ * @returns A readable problem naming both versions and which side to update, or null when they match.
+ */
+function protocolVersionProblem(clientVersion) {
+    const serverVersion = getToolkitRuntime().TOOLKIT.NETWORK_PROTOCOL_VERSION;
+    const sentVersion = (typeof clientVersion === "number") ? clientVersion : null;
+    if (sentVersion === serverVersion)
+        return null;
+    const sideToUpdate = (sentVersion == null || sentVersion < serverVersion) ? "game's Babylon Toolkit runtime" : "Babylon Game Server";
+    return "this server speaks network protocol " + serverVersion + " but the game sent " + (sentVersion ?? "none") + "; update the " + sideToUpdate;
+}
+/**
+ * Runs the token verifier when auth is on (D13).
+ * @param state The server state.
+ * @param token The bearer token ("" when none was sent).
+ * @param kind Which room the join is for.
+ * @param request The join options.
+ * @param clientAddress The client's address.
+ * @param origin The request's Origin, or null.
+ * @returns The verified identity, or null when auth is off.
+ * @throws ServerError(525, "<Reason>: <detail>") when the verifier refuses.
+ */
+async function verifyToken(state, token, kind, request, clientAddress, origin) {
+    if (!needsVerification(state, token))
+        return null;
+    const authRequest = {
+        token: token,
+        kind: kind,
+        sessionName: (kind === "session") ? request.sessionName ?? null : null,
+        gameMode: (kind === "session" && typeof request.gameMode === "number") ? request.gameMode : null,
+        clientAddress: clientAddress,
+        origin: origin
+    };
+    try {
+        return await verifyPlayerToken(state, authRequest);
+    }
+    catch (error) {
+        state.metrics?.countAuthFailure(state.config.auth.mode);
+        return refuse(state, verifierRefusal(error, clientAddress), clientAddress, origin, request);
+    }
+}
+/**
+ * The refusal of a verifier failure: the verifier's own reason, or CustomAuthenticationFailed when the verifier itself
+ * broke (logged as an error, since that is a server or hook bug).
+ * @param error What the verifier threw.
+ * @param clientAddress The client's address, for the log.
+ * @returns The refusal, with status 525 (ErrorCode.AUTH_FAILED).
+ */
+function verifierRefusal(error, clientAddress) {
+    if (error instanceof AuthRefusal)
+        return { status: ErrorCode.AUTH_FAILED, reasonName: error.reasonName, detail: error.detail };
+    getLogger().error("token verifier failed", { clientAddress: clientAddress, error: String(error) });
+    return { status: ErrorCode.AUTH_FAILED, reasonName: "CustomAuthenticationFailed", detail: "the token could not be verified" };
+}
+/**
+ * Counts, logs and throws a refusal.
+ * @param state The server state.
+ * @param refusal The refusal.
+ * @param clientAddress The client's address.
+ * @param origin The request's Origin, or null.
+ * @param request The join options.
+ * @returns Never returns.
+ * @throws ServerError(status, "<Reason>: <detail>").
+ */
+function refuse(state, refusal, clientAddress, origin, request) {
+    state.metrics?.countJoin("refused", refusal.reasonName);
+    getLogger().info("join refused", { reason: refusal.reasonName, detail: refusal.detail, clientAddress: clientAddress, origin: origin, sessionName: request.sessionName });
+    throw new ServerError(refusal.status, refusal.reasonName + ": " + refusal.detail);
+}

package/lib/NetworkAddresses.d.ts

@@ -0,0 +1,33 @@
+import { BlockList } from "node:net";
+/**
+ * Turns an IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) into its IPv4 form, so lists and checks see one spelling.
+ * @param address The client address.
+ * @returns The normalized address.
+ */
+export declare function normalizeAddress(address: string): string;
+/**
+ * Whether an address is this machine's loopback interface (127.0.0.1, ::1 or ::ffff:127.0.0.1).
+ * @param address The client address.
+ * @returns True for a loopback address.
+ */
+export declare function isLoopbackAddress(address: string): boolean;
+/**
+ * Adds one address or CIDR range to a block list.
+ * @param blockList The list to add to.
+ * @param entry An address (`a.b.c.d`, IPv6) or a range (`a.b.c.d/n`).
+ * @returns False when the entry is not an address or range.
+ */
+export declare function addNetworkEntry(blockList: BlockList, entry: string): boolean;
+/**
+ * Builds a block list from address and CIDR entries, skipping invalid ones (config validation reports those).
+ * @param entries The addresses and ranges.
+ * @returns The list.
+ */
+export declare function createNetworkList(entries: string[]): BlockList;
+/**
+ * Whether an address falls inside a block list.
+ * @param blockList The list.
+ * @param address The client address.
+ * @returns True when the address is listed or inside a listed range; false for text that is not an address.
+ */
+export declare function isAddressInList(blockList: BlockList, address: string): boolean;