@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/AbuseLimits.d.ts

@@ -0,0 +1,64 @@
+import type { IncomingMessage, Server as HttpServer } from "node:http";
+import type { LimitsConfig } from "./GameServerConfig.js";
+/**
+ * Limits how many join requests one client address may make per minute (D14), in fixed one-minute windows.
+ */
+export declare class JoinRateLimiter {
+    /** Most join requests per address per window; the console can change it live (game-server-admin-console D20). */
+    private requestsPerMinute;
+    /** The clock, in milliseconds. */
+    private readonly nowMilliseconds;
+    /** The current window of each address seen recently. */
+    private readonly windows;
+    /**
+     * Creates a limiter.
+     * @param requestsPerMinute Most join requests one address may make per minute.
+     * @param nowMilliseconds The clock (Date.now when omitted; tests pass their own).
+     */
+    constructor(requestsPerMinute: number, nowMilliseconds?: () => number);
+    /**
+     * Changes the most join requests one address may make per minute, from the next request on.
+     * @param requestsPerMinute The new limit (more than 0).
+     */
+    setRequestsPerMinute(requestsPerMinute: number): void;
+    /**
+     * Records a join request from an address, when the address still has room in its window.
+     * @param clientAddress The client's address (D11).
+     * @returns True when this address may make another join request now.
+     */
+    tryConsume(clientAddress: string): boolean;
+    /**
+     * Forgets addresses whose window ended more than a window ago, so the map stays small.
+     * @param now The current time, in milliseconds.
+     */
+    private pruneIdleWindows;
+}
+/**
+ * Whether a join from an origin may proceed (D14).
+ * @param origin The request's Origin header, or null when it sent none.
+ * @param limits The limits config.
+ * @returns True when the allow-list is empty, the origin is listed, or a missing origin is allowed.
+ */
+export declare function isOriginAllowed(origin: string | null, limits: LimitsConfig): boolean;
+/**
+ * Checks a session name against the length and character rules (D14).
+ * @param sessionName The requested session name.
+ * @param limits The limits config.
+ * @returns A readable problem, or null when the name is acceptable.
+ */
+export declare function sessionNameProblem(sessionName: string, limits: LimitsConfig): string | null;
+/**
+ * Makes the client address Colyseus reports the socket's own address unless the server sits behind a trusted proxy
+ * (D11). Colyseus builds the matchmaking context's ip from forwarding headers only, so without this any client could
+ * pick its address by sending X-Forwarded-For. Call it after the server listens: the listeners are prepended, so they
+ * run before Colyseus' router.
+ * @param httpServer The transport's HTTP(S) server.
+ * @param trustProxy True to keep the forwarding headers a proxy set.
+ */
+export declare function installClientAddressHeaders(httpServer: HttpServer, trustProxy: boolean): void;
+/**
+ * Replaces a request's forwarding headers with its socket address. It also removes x-forwarded-proto, so a client
+ * without a trusted proxy cannot claim HTTPS and pass the admin console's transport rule (D9).
+ * @param request The incoming request or upgrade.
+ */
+export declare function rewriteClientAddressHeaders(request: IncomingMessage): void;

package/lib/AbuseLimits.js

@@ -0,0 +1,121 @@
+/** Length of one join-rate window, in milliseconds (D14: a fixed one-minute window). */
+const JOIN_RATE_WINDOW_MS = 60000;
+/** Windows an idle address's entry is kept before it is pruned. */
+const PRUNE_AFTER_WINDOWS = 2;
+/** Characters a session name may not contain: C0 controls and DEL. */
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+/** Forwarding headers Colyseus reads the client address from (`@colyseus/core` Transport.ts). */
+const FORWARDING_HEADERS = ["x-forwarded-for", "x-client-ip", "x-real-ip"];
+/** The header the server rewrites to the socket's address, which Colyseus reads first. */
+const REAL_IP_HEADER = "x-real-ip";
+/** The header a proxy names the original scheme in; only a trusted proxy may set it (game-server-admin-console D9). */
+const FORWARDED_PROTO_HEADER = "x-forwarded-proto";
+/**
+ * Limits how many join requests one client address may make per minute (D14), in fixed one-minute windows.
+ */
+export class JoinRateLimiter {
+    /** Most join requests per address per window; the console can change it live (game-server-admin-console D20). */
+    requestsPerMinute;
+    /** The clock, in milliseconds. */
+    nowMilliseconds;
+    /** The current window of each address seen recently. */
+    windows = new Map();
+    /**
+     * Creates a limiter.
+     * @param requestsPerMinute Most join requests one address may make per minute.
+     * @param nowMilliseconds The clock (Date.now when omitted; tests pass their own).
+     */
+    constructor(requestsPerMinute, nowMilliseconds) {
+        this.requestsPerMinute = requestsPerMinute;
+        this.nowMilliseconds = nowMilliseconds ?? Date.now;
+    }
+    /**
+     * Changes the most join requests one address may make per minute, from the next request on.
+     * @param requestsPerMinute The new limit (more than 0).
+     */
+    setRequestsPerMinute(requestsPerMinute) {
+        this.requestsPerMinute = requestsPerMinute;
+    }
+    /**
+     * Records a join request from an address, when the address still has room in its window.
+     * @param clientAddress The client's address (D11).
+     * @returns True when this address may make another join request now.
+     */
+    tryConsume(clientAddress) {
+        const now = this.nowMilliseconds();
+        this.pruneIdleWindows(now);
+        const window = this.windows.get(clientAddress);
+        if (window == null || now - window.windowStartMilliseconds >= JOIN_RATE_WINDOW_MS) {
+            this.windows.set(clientAddress, { windowStartMilliseconds: now, count: 1 });
+            return true;
+        }
+        if (window.count >= this.requestsPerMinute)
+            return false;
+        window.count++;
+        return true;
+    }
+    /**
+     * Forgets addresses whose window ended more than a window ago, so the map stays small.
+     * @param now The current time, in milliseconds.
+     */
+    pruneIdleWindows(now) {
+        const oldestKept = now - PRUNE_AFTER_WINDOWS * JOIN_RATE_WINDOW_MS;
+        for (const [clientAddress, window] of this.windows) {
+            if (window.windowStartMilliseconds < oldestKept)
+                this.windows.delete(clientAddress);
+        }
+    }
+}
+/**
+ * Whether a join from an origin may proceed (D14).
+ * @param origin The request's Origin header, or null when it sent none.
+ * @param limits The limits config.
+ * @returns True when the allow-list is empty, the origin is listed, or a missing origin is allowed.
+ */
+export function isOriginAllowed(origin, limits) {
+    if (limits.allowedOrigins.length === 0)
+        return true;
+    if (origin == null)
+        return limits.allowMissingOrigin;
+    return limits.allowedOrigins.includes(origin);
+}
+/**
+ * Checks a session name against the length and character rules (D14).
+ * @param sessionName The requested session name.
+ * @param limits The limits config.
+ * @returns A readable problem, or null when the name is acceptable.
+ */
+export function sessionNameProblem(sessionName, limits) {
+    if (sessionName.length > limits.maxSessionNameLength)
+        return "session name is longer than " + limits.maxSessionNameLength + " characters";
+    if (CONTROL_CHARACTER_PATTERN.test(sessionName))
+        return "session name contains control characters";
+    return null;
+}
+/**
+ * Makes the client address Colyseus reports the socket's own address unless the server sits behind a trusted proxy
+ * (D11). Colyseus builds the matchmaking context's ip from forwarding headers only, so without this any client could
+ * pick its address by sending X-Forwarded-For. Call it after the server listens: the listeners are prepended, so they
+ * run before Colyseus' router.
+ * @param httpServer The transport's HTTP(S) server.
+ * @param trustProxy True to keep the forwarding headers a proxy set.
+ */
+export function installClientAddressHeaders(httpServer, trustProxy) {
+    if (trustProxy)
+        return;
+    httpServer.prependListener("request", rewriteClientAddressHeaders);
+    httpServer.prependListener("upgrade", rewriteClientAddressHeaders);
+}
+/**
+ * Replaces a request's forwarding headers with its socket address. It also removes x-forwarded-proto, so a client
+ * without a trusted proxy cannot claim HTTPS and pass the admin console's transport rule (D9).
+ * @param request The incoming request or upgrade.
+ */
+export function rewriteClientAddressHeaders(request) {
+    for (const headerName of FORWARDING_HEADERS)
+        delete request.headers[headerName];
+    delete request.headers[FORWARDED_PROTO_HEADER];
+    const remoteAddress = request.socket.remoteAddress;
+    if (remoteAddress != null)
+        request.headers[REAL_IP_HEADER] = remoteAddress;
+}

package/lib/Authentication.d.ts

@@ -0,0 +1,86 @@
+import { type AuthConfig } from "./GameServerConfig.js";
+/** A verified player. */
+export interface AuthIdentity {
+    /** The player's user id from the token or verifier, or null when it names none. */
+    userId: string | null;
+    /** Everything the verifier learned about the player (JWT claims, webhook answer). Never contains the token. */
+    claims: Record<string, unknown>;
+}
+/** What a verifier sees. */
+export interface AuthRequest {
+    /** The bearer token the client sent. */
+    token: string;
+    /** "session" for a session join, "lobby" for the lobby. */
+    kind: "session" | "lobby";
+    /** The requested session name, or null for the lobby. */
+    sessionName: string | null;
+    /** The joiner's TOOLKIT.GameMode, or null for the lobby. */
+    gameMode: number | null;
+    /** The client's address (D11). */
+    clientAddress: string;
+    /** The request's Origin header, or null. */
+    origin: string | null;
+}
+/** A verifier's refusal: the ShutdownReason name and a readable detail (D6). */
+export declare class AuthRefusal extends Error {
+    /** The TOOLKIT.ShutdownReason name the client sees. */
+    readonly reasonName: string;
+    /** The readable detail after the reason name. */
+    readonly detail: string;
+    /**
+     * Creates a refusal whose message is "<reasonName>: <detail>".
+     * @param reasonName The ShutdownReason name.
+     * @param detail A readable detail.
+     */
+    constructor(reasonName: string, detail: string);
+}
+/** Verifies a token; resolves the identity or rejects with AuthRefusal. */
+export type TokenVerifier = (request: AuthRequest) => Promise<AuthIdentity>;
+/** The custom verifier of auth mode "custom" (GameServerHooks.verifyToken). */
+export type CustomTokenVerifier = (request: AuthRequest) => Promise<AuthIdentity | null>;
+/** What the admin console's auth tools can do with a verifier's keys (game-server-admin-console T12). */
+export interface TokenKeyControl {
+    /** Fetches the JWKS again now; null outside JWKS mode. */
+    reloadKeys: (() => Promise<void>) | null;
+    /**
+     * How old the loaded JWKS is.
+     * @returns Seconds since it was last loaded, or null before any load and outside JWKS mode.
+     */
+    keyCacheAgeSeconds: () => number | null;
+}
+/** A token verifier with its key controls (what createTokenVerifier returns). */
+export type ManagedTokenVerifier = TokenVerifier & TokenKeyControl;
+/** The outcome of a token test (the console's token tester). */
+export interface TokenTestResult {
+    /** True when the gate would accept the token. */
+    accepted: boolean;
+    /** The verified identity, or null when refused. */
+    identity: AuthIdentity | null;
+    /** The refusal the gate would answer with ("<ShutdownReason>: <detail>"), or null. */
+    refusal: string | null;
+}
+/**
+ * The token verifier of an auth config (D13): shared secrets, JWTs (secret or JWKS), a webhook, or the custom hook. It
+ * refuses a missing token itself, so each mode only checks a token that was sent.
+ * @param auth The auth config.
+ * @param customVerifier The custom hook (hooks.verifyToken), used by mode "custom".
+ * @returns The verifier.
+ * @throws GameServerConfigError when mode is "custom" and no verifyToken hook was given.
+ */
+export declare function createTokenVerifier(auth: AuthConfig, customVerifier: CustomTokenVerifier | null): ManagedTokenVerifier;
+/**
+ * Tests a player token the way the join gate would (the console's token tester, game-server-admin-console T12): it
+ * calls the verifier directly, so nothing is counted in the metrics and no log line carries the token.
+ * @param verifier The server's verifier (auth must be on).
+ * @param request The token and what the gate would know about the join.
+ * @returns Accepted with the identity, or the refusal the gate would answer with.
+ */
+export declare function testPlayerToken(verifier: TokenVerifier, request: AuthRequest): Promise<TokenTestResult>;
+/**
+ * Compares a sent secret with the expected one in constant time (through SHA-256 digests, so lengths never leak).
+ * The admin API uses it for its bearer token (D15).
+ * @param sentText The secret the request sent.
+ * @param expectedText The configured secret.
+ * @returns True when they are equal.
+ */
+export declare function secretsMatch(sentText: string, expectedText: string): boolean;

package/lib/Authentication.js

@@ -0,0 +1,272 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
+import { GameServerConfigError } from "./GameServerConfig.js";
+/** A verifier's refusal: the ShutdownReason name and a readable detail (D6). */
+export class AuthRefusal extends Error {
+    /** The TOOLKIT.ShutdownReason name the client sees. */
+    reasonName;
+    /** The readable detail after the reason name. */
+    detail;
+    /**
+     * Creates a refusal whose message is "<reasonName>: <detail>".
+     * @param reasonName The ShutdownReason name.
+     * @param detail A readable detail.
+     */
+    constructor(reasonName, detail) {
+        super(reasonName + ": " + detail);
+        this.name = "AuthRefusal";
+        this.reasonName = reasonName;
+        this.detail = detail;
+    }
+}
+/** The key controls of a mode without remote keys. */
+const NO_KEY_CONTROL = { reloadKeys: null, keyCacheAgeSeconds: () => null };
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** The refusal reason the gate uses when a verifier itself breaks. */
+const VERIFIER_FAILURE_REFUSAL = "CustomAuthenticationFailed: the token could not be verified";
+/** ShutdownReason name of a missing or wrong token. */
+const INVALID_AUTHENTICATION = "InvalidAuthentication";
+/** ShutdownReason name of an expired token. */
+const TICKET_EXPIRED = "AuthenticationTicketExpired";
+/** ShutdownReason name of a refusal by the webhook or the custom verifier. */
+const CUSTOM_AUTHENTICATION_FAILED = "CustomAuthenticationFailed";
+/** Milliseconds a fetched JWKS stays cached (D13). */
+const JWKS_CACHE_MAX_AGE_MS = 600000;
+/** Milliseconds between JWKS refetches for an unknown key id (D13). */
+const JWKS_COOLDOWN_MS = 30000;
+/** jose error codes that mean the JWKS itself could not be fetched or read. */
+const JWKS_UNAVAILABLE_CODES = [joseErrors.JWKSTimeout.code, joseErrors.JWKSInvalid.code, joseErrors.JOSEError.code];
+/**
+ * The token verifier of an auth config (D13): shared secrets, JWTs (secret or JWKS), a webhook, or the custom hook. It
+ * refuses a missing token itself, so each mode only checks a token that was sent.
+ * @param auth The auth config.
+ * @param customVerifier The custom hook (hooks.verifyToken), used by mode "custom".
+ * @returns The verifier.
+ * @throws GameServerConfigError when mode is "custom" and no verifyToken hook was given.
+ */
+export function createTokenVerifier(auth, customVerifier) {
+    const modeVerifier = createModeVerifier(auth, customVerifier);
+    const verifier = async (request) => {
+        if (request.token === "")
+            throw new AuthRefusal(INVALID_AUTHENTICATION, "no token was sent");
+        return modeVerifier.verify(request);
+    };
+    return Object.assign(verifier, { reloadKeys: modeVerifier.keys.reloadKeys, keyCacheAgeSeconds: modeVerifier.keys.keyCacheAgeSeconds });
+}
+/**
+ * Tests a player token the way the join gate would (the console's token tester, game-server-admin-console T12): it
+ * calls the verifier directly, so nothing is counted in the metrics and no log line carries the token.
+ * @param verifier The server's verifier (auth must be on).
+ * @param request The token and what the gate would know about the join.
+ * @returns Accepted with the identity, or the refusal the gate would answer with.
+ */
+export async function testPlayerToken(verifier, request) {
+    try {
+        const identity = await verifier(request);
+        return { accepted: true, identity: identity, refusal: null };
+    }
+    catch (error) {
+        const refusal = (error instanceof AuthRefusal) ? error.reasonName + ": " + error.detail : VERIFIER_FAILURE_REFUSAL;
+        return { accepted: false, identity: null, refusal: refusal };
+    }
+}
+/**
+ * The verifier of the configured mode.
+ * @param auth The auth config.
+ * @param customVerifier The custom hook, or null.
+ * @returns The verifier of a token that was sent.
+ * @throws GameServerConfigError when mode is "custom" without a hook.
+ */
+function createModeVerifier(auth, customVerifier) {
+    switch (auth.mode) {
+        case "shared-secret":
+            return { verify: createSharedSecretVerifier(auth.sharedSecret.tokens), keys: NO_KEY_CONTROL };
+        case "jwt":
+            return createJwtVerifier(auth.jwt);
+        case "webhook":
+            return { verify: createWebhookVerifier(auth.webhook), keys: NO_KEY_CONTROL };
+        case "custom":
+            if (customVerifier == null)
+                throw new GameServerConfigError(["auth.mode \"custom\" needs a verifyToken hook (createGameServer({ hooks: { verifyToken } }))"]);
+            return { verify: createCustomVerifier(customVerifier), keys: NO_KEY_CONTROL };
+    }
+}
+/**
+ * Shared-secret mode: the token must equal one of the configured tokens, compared in constant time.
+ * @param tokens The accepted tokens.
+ * @returns The verifier.
+ */
+function createSharedSecretVerifier(tokens) {
+    const tokenDigests = tokens.map(sha256Digest);
+    return async (request) => {
+        const sentDigest = sha256Digest(request.token);
+        // Compare against every token so the time taken never says which one (or whether any) matched.
+        let matchedIndex = -1;
+        tokenDigests.forEach((tokenDigest, keyIndex) => {
+            if (timingSafeEqual(sentDigest, tokenDigest) && matchedIndex < 0)
+                matchedIndex = keyIndex;
+        });
+        if (matchedIndex < 0)
+            throw new AuthRefusal(INVALID_AUTHENTICATION, "the token is not valid");
+        return { userId: null, claims: { method: "shared-secret", keyIndex: matchedIndex } };
+    };
+}
+/**
+ * JWT mode: jose's jwtVerify against a shared secret (HS*) or a remote JWKS, with the configured issuer, audience and
+ * algorithms.
+ * @param jwt The JWT config.
+ * @returns The verifier and its key controls.
+ */
+function createJwtVerifier(jwt) {
+    const verifyOptions = {};
+    if (jwt.issuer != null)
+        verifyOptions.issuer = jwt.issuer;
+    if (jwt.audience != null)
+        verifyOptions.audience = jwt.audience;
+    if (jwt.algorithms.length > 0)
+        verifyOptions.algorithms = jwt.algorithms;
+    const signatureCheck = createJwtSignatureCheck(jwt, verifyOptions);
+    const usesJwks = jwt.jwksUrl != null;
+    const verify = async (request) => {
+        let payload;
+        try {
+            payload = await signatureCheck.verify(request.token);
+        }
+        catch (error) {
+            throw jwtRefusal(error, usesJwks);
+        }
+        const userId = (typeof payload.sub === "string") ? payload.sub : null;
+        return { userId: userId, claims: payload };
+    };
+    return { verify: verify, keys: signatureCheck.keys };
+}
+/**
+ * The jwtVerify call of a JWT config: against the remote JWKS when jwksUrl is set, else the shared secret (validation
+ * guarantees one of them).
+ * @param jwt The JWT config.
+ * @param verifyOptions The issuer, audience and algorithm checks.
+ * @returns The check and its key controls (reload and cache age with a JWKS).
+ */
+function createJwtSignatureCheck(jwt, verifyOptions) {
+    if (jwt.jwksUrl != null)
+        return createJwksSignatureCheck(new URL(jwt.jwksUrl), verifyOptions);
+    const secretKey = new TextEncoder().encode(jwt.secret ?? "");
+    return { verify: async (token) => (await jwtVerify(token, secretKey, verifyOptions)).payload, keys: NO_KEY_CONTROL };
+}
+/**
+ * The jwtVerify call against a remote JWKS, which jose caches. The load time is noted whenever jose's key set object
+ * changes (a first fetch, a cache refresh or a reload), so the console can show the cache's age.
+ * @param jwksUrl The JWKS URL.
+ * @param verifyOptions The issuer, audience and algorithm checks.
+ * @returns The check with reload and cache age.
+ */
+function createJwksSignatureCheck(jwksUrl, verifyOptions) {
+    const remoteKeys = createRemoteJWKSet(jwksUrl, { cacheMaxAge: JWKS_CACHE_MAX_AGE_MS, cooldownDuration: JWKS_COOLDOWN_MS });
+    let loadedAt = null;
+    let seenKeySet = undefined;
+    const noteLoadedKeys = () => {
+        const keySet = remoteKeys.jwks();
+        if (keySet == null || keySet === seenKeySet)
+            return;
+        seenKeySet = keySet;
+        loadedAt = Date.now();
+    };
+    const verify = async (token) => {
+        try {
+            return (await jwtVerify(token, remoteKeys, verifyOptions)).payload;
+        }
+        finally {
+            noteLoadedKeys();
+        }
+    };
+    const reloadKeys = async () => {
+        await remoteKeys.reload();
+        noteLoadedKeys();
+    };
+    const keyCacheAgeSeconds = () => (loadedAt == null) ? null : (Date.now() - loadedAt) / MILLISECONDS_PER_SECOND;
+    return { verify: verify, keys: { reloadKeys: reloadKeys, keyCacheAgeSeconds: keyCacheAgeSeconds } };
+}
+/**
+ * The refusal of a failed JWT check (D13 refusal texts).
+ * @param error What jwtVerify threw.
+ * @param usesJwks True when keys come from a JWKS URL (a fetch failure then means the keys could not be loaded).
+ * @returns The refusal.
+ */
+function jwtRefusal(error, usesJwks) {
+    if (error instanceof joseErrors.JWTExpired)
+        return new AuthRefusal(TICKET_EXPIRED, "the token has expired");
+    const isJoseError = error instanceof joseErrors.JOSEError;
+    const errorCode = isJoseError ? error.code : "";
+    const keysUnavailable = usesJwks && (!isJoseError || JWKS_UNAVAILABLE_CODES.includes(errorCode));
+    if (keysUnavailable)
+        return new AuthRefusal(INVALID_AUTHENTICATION, "the identity provider's keys could not be loaded");
+    const detailCode = isJoseError ? errorCode : "ERR_JWT_INVALID";
+    return new AuthRefusal(INVALID_AUTHENTICATION, "the token is not valid (" + detailCode + ")");
+}
+/**
+ * Webhook mode: POSTs the token and what the server knows about the join to a URL; a 2xx JSON object approves.
+ * @param webhook The webhook config (url is set: validation requires it).
+ * @returns The verifier.
+ */
+function createWebhookVerifier(webhook) {
+    const webhookUrl = webhook.url ?? "";
+    return async (request) => {
+        const body = await postToWebhook(webhookUrl, webhook.timeoutMs, request);
+        if (body == null)
+            throw new AuthRefusal(CUSTOM_AUTHENTICATION_FAILED, "the auth webhook did not approve the player");
+        const userId = (typeof body.userId === "string") ? body.userId : null;
+        return { userId: userId, claims: body };
+    };
+}
+/**
+ * Asks the webhook about a join.
+ * @param webhookUrl The webhook URL.
+ * @param timeoutMs Milliseconds to wait for the answer.
+ * @param request The join.
+ * @returns The answer's JSON object, or null when it did not approve (not 2xx, timeout, not a JSON object).
+ */
+async function postToWebhook(webhookUrl, timeoutMs, request) {
+    const payload = JSON.stringify({ token: request.token, kind: request.kind, sessionName: request.sessionName, gameMode: request.gameMode, clientAddress: request.clientAddress, origin: request.origin });
+    try {
+        const response = await fetch(webhookUrl, { method: "POST", headers: { "content-type": "application/json" }, body: payload, signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        return (body != null && typeof body === "object" && !Array.isArray(body)) ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Custom mode: the developer's hook decides.
+ * @param customVerifier The hook.
+ * @returns The verifier.
+ */
+function createCustomVerifier(customVerifier) {
+    return async (request) => {
+        const identity = await customVerifier(request);
+        if (identity == null)
+            throw new AuthRefusal(CUSTOM_AUTHENTICATION_FAILED, "the custom verifier did not approve the player");
+        return identity;
+    };
+}
+/**
+ * Compares a sent secret with the expected one in constant time (through SHA-256 digests, so lengths never leak).
+ * The admin API uses it for its bearer token (D15).
+ * @param sentText The secret the request sent.
+ * @param expectedText The configured secret.
+ * @returns True when they are equal.
+ */
+export function secretsMatch(sentText, expectedText) {
+    return timingSafeEqual(sha256Digest(sentText), sha256Digest(expectedText));
+}
+/**
+ * The SHA-256 digest of a text, so tokens of any length compare in constant time.
+ * @param text The text.
+ * @returns The 32-byte digest.
+ */
+function sha256Digest(text) {
+    return createHash("sha256").update(text, "utf8").digest();
+}

package/lib/BootSessionOwner.d.ts

@@ -0,0 +1,86 @@
+import type { AdminClock } from "./admin/AdminClock.js";
+/** The store lease whose holder runs the boot dedicated sessions. */
+export declare const BOOT_SESSION_LEASE_NAME: string;
+/** What a BootSessionOwner needs from the running server. */
+export interface BootSessionOwnerDependencies {
+    /**
+     * Takes the boot session lease, or renews it when this holder has it.
+     * @param holderId The would-be holder.
+     * @param ttlMilliseconds The lease length.
+     * @returns True when this holder now holds it.
+     * @throws Error when the store cannot answer.
+     */
+    tryAcquireLease(holderId: string, ttlMilliseconds: number): Promise<boolean>;
+    /**
+     * Starts the boot dedicated sessions that can start now. It is called again on a later tick until it returns true,
+     * so it must skip what an earlier call started.
+     * @returns True when all of them run; false when some must wait, for example for a draining process's session of
+     *     the same name to end.
+     * @throws Error when a session cannot start.
+     */
+    startSessions(): Promise<boolean>;
+    /**
+     * This process's id, unique across the deploy. Called only after the server listens.
+     * @returns The id.
+     */
+    holderId(): string;
+    /**
+     * Whether this process drains, and so must let the lease lapse.
+     * @returns True once a drain started.
+     */
+    isDraining(): boolean;
+    /** The time and timers. */
+    clock: AdminClock;
+}
+/**
+ * Holds the boot session lease and starts the boot dedicated sessions on the process that gets it. A process that does
+ * not hold the lease keeps asking; a draining holder stops renewing, so a process of the next generation takes over
+ * within LEADER_LEASE_TTL_MS.
+ */
+export declare class BootSessionOwner {
+    /** What it needs from the running server. */
+    private readonly dependencies;
+    /** The renewal timer, while started. */
+    private renewTimer;
+    /** What the last look at the lease found; logged only when it changes. */
+    private leaseState;
+    /** True once this process runs every boot session. */
+    private areSessionsStarted;
+    /** True while a start runs: a scene can load for longer than a tick, and the lease must keep renewing meanwhile. */
+    private isStarting;
+    /**
+     * Prepares the owner; nothing runs until start().
+     * @param dependencies What it needs from the running server.
+     */
+    constructor(dependencies: BootSessionOwnerDependencies);
+    /**
+     * Runs the first attempt and keeps trying every LEADER_RENEW_INTERVAL_MS. The timer starts first, so a slow scene
+     * load cannot let the lease lapse.
+     * @throws Error when this process gets the lease and a boot session cannot start; the owner is stopped first.
+     */
+    start(): Promise<void>;
+    /** Stops the timer. The lease runs out by itself after LEADER_LEASE_TTL_MS. */
+    stop(): void;
+    /**
+     * One timer tick: renews the lease and starts the sessions when due, unless this process drains. A failure never
+     * reaches the running process: it is logged, and the next tick tries again.
+     */
+    tick(): Promise<void>;
+    /**
+     * Renews the lease, then starts the sessions when this process holds it and has not started them.
+     * @throws Error when a session cannot start.
+     */
+    private attempt;
+    /**
+     * Takes or renews the lease; a store failure counts as not holding it.
+     * @returns True while this process holds the lease.
+     */
+    private renewLease;
+    /**
+     * Logs a change of the lease state, so a process that waits for hours writes one line.
+     * @param leaseState What this look found.
+     * @param holderId This process's id.
+     * @param failure Why the store could not answer, when it could not.
+     */
+    private reportLeaseState;
+}