@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/AdminConsole.js

@@ -0,0 +1,325 @@
+// The console's composition root (game-server-admin-console D1, D6, D30): it builds the admin services, owns the four
+// router entries of the app and its API, and starts and stops the console's timers.
+import { createEndpoint } from "colyseus";
+import { fileURLToPath } from "node:url";
+import { getLogger } from "../GameServerLogger.js";
+import { registerAccountRoutes } from "./AccountRoutes.js";
+import { AdminAccounts } from "./AdminAccounts.js";
+import { AdminAudit } from "./AdminAudit.js";
+import { ADMIN_API_PREFIX, AUDIT_RETENTION_INTERVAL_MS, CONSOLE_BASE_PATH, CONSOLE_ROOT_PATH, SESSION_SWEEP_INTERVAL_MS } from "./AdminConstants.js";
+import { registerApiKeyRoutes } from "./ApiKeyRoutes.js";
+import { ApiKeys } from "./ApiKeys.js";
+import { registerAuditRoutes } from "./AuditRoutes.js";
+import { registerUserRoutes } from "./UserRoutes.js";
+import { AdminApiRouter, requestOf } from "./AdminApiRouter.js";
+import { AdminRequestGate } from "./AdminRequestGate.js";
+import { adminJsonResponse, consoleOriginOf, redirectResponse } from "./AdminResponses.js";
+import { AdminStaticFiles } from "./AdminStaticFiles.js";
+import { registerAuthToolCommands, registerAuthToolRoutes } from "./AuthToolRoutes.js";
+import { ConfigOverrides } from "./ConfigOverrides.js";
+import { registerConfigRoutes } from "./ConfigRoutes.js";
+import { ConsoleSessions } from "./ConsoleSessions.js";
+import { registerDedicatedCommands, registerDedicatedRoutes } from "./DedicatedRoutes.js";
+import { FleetDirectory } from "./FleetDirectory.js";
+import { createNoticePayload, registerFleetCommands, registerFleetRoutes } from "./FleetRoutes.js";
+import { MaintenanceMode } from "./MaintenanceMode.js";
+import { registerLogCommands, registerLogRoutes, TemporaryLogLevel } from "./LogRoutes.js";
+import { registerMetricsRoutes } from "./MetricsRoutes.js";
+import { MetricsSampler } from "./MetricsSampler.js";
+import { BanList } from "./BanList.js";
+import { registerPlayerCommands, registerPlayerRoutes, reloadBanList } from "./PlayerRoutes.js";
+import { registerSessionCommands, registerSessionRoutes, RoomAdminClient } from "./SessionRoutes.js";
+import { AlertEngine } from "./AlertEngine.js";
+import { registerAlertRoutes } from "./AlertRoutes.js";
+import { registerExtensionRoutes } from "./ExtensionRoutes.js";
+import { registerColyseusCloudRoutes } from "./ColyseusCloudRoutes.js";
+import { registerLeaderboardRoutes } from "./LeaderboardRoutes.js";
+import { ColyseusCloudService } from "./ColyseusCloudService.js";
+import { FleetLeader } from "./FleetLeader.js";
+import { MaintenanceWindows } from "./MaintenanceWindows.js";
+import { RolloutCoordinator } from "./RolloutCoordinator.js";
+import { OpenIdConnectClient } from "./OpenIdConnect.js";
+import { Passkeys } from "./Passkeys.js";
+import { InstanceEventTracker, ServerEvents } from "./ServerEvents.js";
+/** Where Vite builds the console app: lib/console/, beside lib/admin/. */
+const CONSOLE_FILES_FOLDER = fileURLToPath(new URL("../console/", import.meta.url));
+/** The asset path prefix that belongs to the API, never to the app. */
+const API_ASSET_PREFIX = "api";
+/** HTTP status of a refused or unknown console path. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of the transport rule's refusal. */
+const HTTP_FORBIDDEN = 403;
+/** Warning logged when the file store would lose its data on a container restart (DR §9). */
+const STORE_NOT_PERSISTENT_WARNING = "admin data is stored inside the container and will be lost on restart";
+/** The console of one game server process. */
+class AdminConsoleHost {
+    /** The shared services. */
+    services;
+    /** The built app's files. */
+    staticFiles;
+    /** The network restriction and transport rule. */
+    gate;
+    /** The API dispatcher. */
+    apiRouter;
+    /** The expired-session sweep timer, while started. */
+    sweepTimer = null;
+    /** The hourly audit retention timer, while started. */
+    retentionTimer = null;
+    /** Instances joining and getting lost, as the leader sees them. */
+    instanceEvents;
+    /**
+     * Builds the console's parts; nothing runs until start().
+     * @param services The shared services.
+     */
+    constructor(services) {
+        this.services = services;
+        this.staticFiles = new AdminStaticFiles(CONSOLE_FILES_FOLDER);
+        this.gate = new AdminRequestGate(services.config);
+        this.apiRouter = new AdminApiRouter(services, this.gate, () => this.isAvailable());
+        registerAccountRoutes(this.apiRouter, services);
+        registerUserRoutes(this.apiRouter, services);
+        registerApiKeyRoutes(this.apiRouter, services);
+        registerAuditRoutes(this.apiRouter, services);
+        registerFleetRoutes(this.apiRouter, services);
+        registerFleetCommands(services);
+        registerSessionRoutes(this.apiRouter, services);
+        registerSessionCommands(services);
+        registerPlayerRoutes(this.apiRouter, services);
+        registerPlayerCommands(services);
+        registerDedicatedRoutes(this.apiRouter, services);
+        registerDedicatedCommands(services);
+        registerMetricsRoutes(this.apiRouter, services);
+        registerLogRoutes(this.apiRouter, services);
+        registerLogCommands(services);
+        registerConfigRoutes(this.apiRouter, services);
+        registerAuthToolRoutes(this.apiRouter, services);
+        registerAuthToolCommands(services);
+        registerAlertRoutes(this.apiRouter, services);
+        registerExtensionRoutes(this.apiRouter, services);
+        registerColyseusCloudRoutes(this.apiRouter, services);
+        registerLeaderboardRoutes(this.apiRouter, services);
+        services.alerts.onAlertFired((alert) => services.extensions.callHook("onAlertFired", { alertId: alert.alertId, ruleId: alert.ruleId, severity: alert.severity, summary: alert.summary }));
+        services.maintenanceWindows.onMaintenanceChanged((enabled, message) => services.extensions.callHook("onMaintenanceChanged", { enabled: enabled, scope: "fleet", message: message, by: "maintenance window" }));
+        this.instanceEvents = new InstanceEventTracker(services.serverEvents);
+        services.leader.addTickHandler(async () => this.instanceEvents.observe(await services.fleet.listInstances()));
+        services.leader.addTickHandler(() => services.alerts.evaluate());
+        services.leader.addTickHandler(() => services.maintenanceWindows.tick());
+        services.leader.addTickHandler(() => services.rollouts.tick());
+        if (services.colyseusCloud.isConfigured)
+            services.leader.addTickHandler(() => services.colyseusCloud.refreshDue());
+        services.fleet.onChange((collection) => this.reloadCollection(collection));
+        services.accounts.onLockout((user, clientAddress) => this.auditLockout(user, clientAddress));
+        services.routeContext.auditLegacyAdmin = (action, target) => this.auditLegacyCall(action, target);
+    }
+    /**
+     * Builds the router endpoints of the console app and its API (D1, D6).
+     * @returns The endpoints, keyed for createRouter.
+     */
+    routes() {
+        return {
+            adminConsoleIndex: createEndpoint(CONSOLE_BASE_PATH, { method: "GET" }, async (context) => this.respondStatic("", context)),
+            adminConsoleAsset: createEndpoint(CONSOLE_BASE_PATH + "**:assetPath", { method: "GET" }, async (context) => this.respondStatic(String(context.params?.assetPath ?? ""), context)),
+            adminConsoleApi: createEndpoint(ADMIN_API_PREFIX + "**:apiPath", { method: ["GET", "POST", "PUT", "DELETE"], disableBody: true }, async (context) => this.apiRouter.handle(context))
+        };
+    }
+    /**
+     * Answers GET /game-server/admin with a 308 to /game-server/admin/ (see AdminConsole.redirectBarePath).
+     * @param request The incoming request.
+     * @returns The redirect, or undefined for any other request.
+     */
+    redirectBarePath(request) {
+        if (request.method !== "GET" || new URL(request.url).pathname !== CONSOLE_ROOT_PATH)
+            return undefined;
+        return redirectResponse(CONSOLE_BASE_PATH);
+    }
+    /** Reads the built app into memory. */
+    async loadFiles() {
+        await this.staticFiles.load();
+    }
+    /**
+     * Starts the console: warns when its file store would not survive a container restart, offers the first-owner
+     * setup link when no account exists (D30), applies the stored fleet maintenance and bans, keeps player history, joins
+     * the fleet (D16), samples metrics (D22), applies a stored fleet log level (D21) and this instance's own config
+     * overrides (D20), and sweeps expired sessions every SESSION_SWEEP_INTERVAL_MS.
+     */
+    async start() {
+        if (!this.services.store.isPersistent)
+            getLogger().warn(STORE_NOT_PERSISTENT_WARNING, { dataDir: this.services.config.admin.dataDir });
+        await this.services.accounts.ensureSetupLink(this.services.routeContext.urls());
+        await this.services.maintenance.reloadFleetSetting(this.services.store);
+        await reloadBanList(this.services);
+        await this.services.temporaryLogLevel.applyStored();
+        await this.services.configOverrides.reload();
+        this.services.state.banList = this.services.banList;
+        this.services.state.onPlayerSessionEvent = (event) => this.recordPlayerSession(event);
+        await this.services.fleet.start();
+        await this.services.leader.start();
+        this.services.metricsSampler.start();
+        this.sweepTimer = this.services.clock.setInterval(() => this.sweepSessions(), SESSION_SWEEP_INTERVAL_MS);
+        this.retentionTimer = this.services.clock.setInterval(() => this.applyAuditRetention(), AUDIT_RETENTION_INTERVAL_MS);
+    }
+    /**
+     * Stops the console's timers, metrics sampling and the pending log level revert, leaves the fleet, stops enforcing
+     * bans and removes the legacy audit and history hooks.
+     */
+    async stop() {
+        this.services.leader.stop();
+        this.services.metricsSampler.stop();
+        this.services.temporaryLogLevel.stop();
+        await this.services.fleet.stop();
+        this.services.state.banList = null;
+        this.services.state.onPlayerSessionEvent = null;
+        if (this.sweepTimer != null)
+            this.services.clock.clearInterval(this.sweepTimer);
+        if (this.retentionTimer != null)
+            this.services.clock.clearInterval(this.retentionTimer);
+        this.sweepTimer = null;
+        this.retentionTimer = null;
+        delete this.services.routeContext.auditLegacyAdmin;
+    }
+    /**
+     * Whether the API answers (R6).
+     * @returns True when admin.console is on and a user exists or admin.token is set.
+     */
+    async isAvailable() {
+        if (!this.services.config.admin.console)
+            return false;
+        return this.services.config.admin.token != null || await this.isAppAvailable();
+    }
+    /**
+     * Whether the app pages are served (R6): admin.console on and a user exists or a setup is pending.
+     * @returns True when they are served.
+     */
+    async isAppAvailable() {
+        if (!this.services.config.admin.console)
+            return false;
+        return this.services.accounts.hasPendingSetup() || await this.services.accounts.hasUsers();
+    }
+    /**
+     * Reloads what a change announcement names: the fleet maintenance setting and the config overrides, or the bans. A
+     * store failure is logged.
+     * @param collection The changed collection.
+     */
+    reloadCollection(collection) {
+        const logFailure = (error) => getLogger().warn("admin " + collection + " could not be reloaded", { error: String(error) });
+        if (collection === "settings")
+            this.services.maintenance.reloadFleetSetting(this.services.store).catch(logFailure);
+        if (collection === "settings")
+            this.services.configOverrides.reload().catch(logFailure);
+        if (collection === "bans")
+            reloadBanList(this.services).catch(logFailure);
+    }
+    /**
+     * Appends a player join or leave to the playerHistory stream, under the same rule as legacy audit records (R3).
+     * @param event The join or leave.
+     */
+    recordPlayerSession(event) {
+        this.isRecordKeepingOn()
+            .then((isKept) => isKept ? this.services.store.appendRecord("playerHistory", event) : undefined)
+            .catch((error) => getLogger().warn("player history could not be recorded", { error: String(error) }));
+    }
+    /** Applies the audit retention; a store failure is logged and retried next hour. */
+    applyAuditRetention() {
+        this.services.audit.applyRetention().catch((error) => getLogger().warn("admin audit retention failed", { error: String(error) }));
+    }
+    /**
+     * Audits an account lockout as the system actor.
+     * @param user The locked account.
+     * @param clientAddress The address of the last failure.
+     */
+    auditLockout(user, clientAddress) {
+        void this.services.audit.recordSafely({ actor: { kind: "system", id: "system", name: "system" }, clientAddress: clientAddress, processId: this.services.processId(), action: "auth.lockout", target: user.username, parameters: {}, result: { ok: true, detail: null } });
+    }
+    /**
+     * Audits a successful legacy admin endpoint call as the legacy token (T3). A token-only server with a file store and
+     * no admin account skips it, so such deployments never create the data folder (R3).
+     * @param action The legacy action.
+     * @param target The room id or session name, or null.
+     */
+    auditLegacyCall(action, target) {
+        const entry = { actor: { kind: "legacyToken", id: "legacy", name: "legacy admin token" }, clientAddress: null, processId: this.services.processId(), action: action, target: target, parameters: {}, result: { ok: true, detail: null } };
+        this.isRecordKeepingOn().then((isKept) => isKept ? this.services.audit.recordSafely(entry) : undefined, (error) => getLogger().error("admin audit record failed", { action: action, error: String(error) }));
+    }
+    /**
+     * Appends a server event of this instance to the activity feed.
+     * @param text What happened.
+     */
+    recordServerEvent(text) {
+        this.services.serverEvents.record(text, this.services.processId());
+    }
+    /**
+     * Whether the console writes records nobody asked for (R3, see ServerEvents.isRecordKeepingOn).
+     * @returns True when such records are kept.
+     */
+    isRecordKeepingOn() {
+        return this.services.serverEvents.isRecordKeepingOn();
+    }
+    /** Deletes expired sessions and pending sign-ins; a store failure is logged and retried next time. */
+    sweepSessions() {
+        this.services.sessions.sweepExpired().catch((error) => getLogger().warn("admin session sweep failed", { error: String(error) }));
+    }
+    /**
+     * Answers an app path: refused outside admin.allowedNetworks or while the app is off (404), never for an api/
+     * path (404 JSON), refused without HTTPS from other machines (403), else the static file.
+     * @param assetPath The path after /game-server/admin/.
+     * @param context The router context.
+     * @returns The response.
+     */
+    async respondStatic(assetPath, context) {
+        const headers = requestOf(context).headers;
+        const clientAddress = AdminRequestGate.clientAddressOf(headers);
+        const consoleOrigin = consoleOriginOf(headers, this.gate.isSecureRequest(headers));
+        const isApiPath = assetPath === API_ASSET_PREFIX || assetPath.startsWith(API_ASSET_PREFIX + "/");
+        if (isApiPath || !this.gate.isNetworkAllowed(clientAddress) || !(await this.isAppAvailable())) {
+            return adminJsonResponse(HTTP_NOT_FOUND, { error: "not found" }, consoleOrigin);
+        }
+        if (!this.gate.isTransportSafe(headers, clientAddress))
+            return adminJsonResponse(HTTP_FORBIDDEN, { error: "the console needs HTTPS" }, consoleOrigin);
+        return this.staticFiles.respond(assetPath);
+    }
+}
+/**
+ * Builds the console of this process: its services, its static files (read into memory now) and its API routes. The
+ * console is started but not listening; GameServer.ts merges routes() into the router and calls start() after listen.
+ * @param core What GameServer.ts hands the console.
+ * @returns The console.
+ */
+export async function createAdminConsole(core) {
+    const sessions = new ConsoleSessions(core.store, core.clock, core.config.admin.sessionIdleMinutes, core.config.admin.sessionMaxHours);
+    const accounts = new AdminAccounts(core.store, core.clock, sessions, core.config.admin.console);
+    const apiKeys = new ApiKeys(core.store, core.clock);
+    const audit = new AdminAudit(core.store, core.clock, core.processId);
+    const fleet = new FleetDirectory(core);
+    const maintenance = new MaintenanceMode(core.state);
+    const banList = new BanList(() => core.clock.now());
+    const configOverrides = new ConfigOverrides(core, fleet);
+    // The stored fleet overrides apply before the server listens, so no session starts with the old values (D20).
+    await configOverrides.applyStored();
+    const metricsSampler = new MetricsSampler(core);
+    const serverEvents = new ServerEvents(core.store, core.clock, accounts);
+    const createWarningNotice = (text, countdownSeconds) => createNoticePayload(core, text, "warning", countdownSeconds);
+    const services = Object.assign({}, core, {
+        sessions: sessions,
+        accounts: accounts,
+        apiKeys: apiKeys,
+        audit: audit,
+        fleet: fleet,
+        maintenance: maintenance,
+        roomClient: new RoomAdminClient(),
+        banList: banList,
+        metricsSampler: metricsSampler,
+        temporaryLogLevel: new TemporaryLogLevel(core),
+        configOverrides: configOverrides,
+        serverEvents: serverEvents,
+        leader: new FleetLeader(core),
+        alerts: new AlertEngine(core, fleet, serverEvents, metricsSampler),
+        maintenanceWindows: new MaintenanceWindows(core, fleet, maintenance, serverEvents, createWarningNotice),
+        rollouts: new RolloutCoordinator(core, fleet, serverEvents),
+        passkeys: new Passkeys(core.store, core.clock, core.config.admin.passkeys, accounts),
+        openId: new OpenIdConnectClient(core.config.admin.oidc, core.store, core.clock, accounts),
+        colyseusCloud: new ColyseusCloudService(core)
+    });
+    const host = new AdminConsoleHost(services);
+    await host.loadFiles();
+    return host;
+}

package/lib/admin/AdminConstants.d.ts

@@ -0,0 +1,147 @@
+import type { CloudResourceName } from "./AdminApiTypes.js";
+/** URL path of the console app (with its trailing slash, D1). */
+export declare const CONSOLE_BASE_PATH: string;
+/** URL of the console without its trailing slash (the redirect source). */
+export declare const CONSOLE_ROOT_PATH: string;
+/** URL path prefix of the console API (D1, D6). */
+export declare const ADMIN_API_PREFIX: string;
+/** Largest admin request body read, in bytes (D6). */
+export declare const ADMIN_MAX_BODY_BYTES: number;
+/** How long a step-up (second factor re-check) stays valid, in milliseconds (D10). */
+export declare const STEP_UP_WINDOW_MS: number;
+/** How long a first-owner setup link stays valid, in milliseconds (D30). */
+export declare const SETUP_LINK_LIFETIME_MS: number;
+/** How long a half-finished sign-in (password checked, second factor pending) stays valid, in milliseconds. */
+export declare const PENDING_SIGN_IN_LIFETIME_MS: number;
+/** Failed sign-ins of one account within the lockout window that lock it (spec 1). */
+export declare const ACCOUNT_LOCKOUT_FAILURES: number;
+/** The lockout counting window and the lock duration, in milliseconds. */
+export declare const ACCOUNT_LOCKOUT_WINDOW_MS: number;
+/** Failed sign-ins from one address within the lockout window before it is refused with 429. */
+export declare const ADDRESS_SIGN_IN_FAILURES: number;
+/** Extra delay added per recent failure before a failed sign-in answers, in milliseconds. */
+export declare const SIGN_IN_DELAY_STEP_MS: number;
+/** Cap of the failed sign-in delay, in milliseconds. */
+export declare const SIGN_IN_DELAY_MAX_MS: number;
+/** Minimum admin password length (D8). */
+export declare const MINIMUM_PASSWORD_LENGTH: number;
+/** Number of one-time recovery codes an account gets (D8). */
+export declare const RECOVERY_CODE_COUNT: number;
+/** TOTP time step, in seconds (D8). */
+export declare const TOTP_STEP_SECONDS: number;
+/** Digits of a TOTP code (D8). */
+export declare const TOTP_DIGITS: number;
+/** Steps before and after the current one a TOTP code may come from (clock skew, D8). */
+export declare const TOTP_ALLOWED_DRIFT_STEPS: number;
+/** Bytes of a TOTP secret (D8). */
+export declare const TOTP_SECRET_BYTES: number;
+/** scrypt CPU/memory cost N (D8). */
+export declare const SCRYPT_COST: number;
+/** scrypt block size r (D8). */
+export declare const SCRYPT_BLOCK_SIZE: number;
+/** scrypt parallelism p (D8). */
+export declare const SCRYPT_PARALLELISM: number;
+/** Bytes of a scrypt password hash (D8). */
+export declare const SCRYPT_KEY_BYTES: number;
+/** Bytes of a scrypt salt (D8). */
+export declare const SCRYPT_SALT_BYTES: number;
+/** How often each instance publishes its heartbeat, in milliseconds (D16). */
+export declare const FLEET_HEARTBEAT_INTERVAL_MS: number;
+/** An instance silent this long is "lost", in milliseconds (D16). */
+export declare const FLEET_LOST_AFTER_MS: number;
+/** A lost instance is forgotten after this long, in milliseconds (D16). */
+export declare const FLEET_FORGET_AFTER_MS: number;
+/** How long a fleet command waits for its reply, in milliseconds (D16). */
+export declare const FLEET_COMMAND_TIMEOUT_MS: number;
+/** Presence hash of the fleet's heartbeats (D16). */
+export declare const FLEET_INSTANCES_KEY: string;
+/** Presence topic prefix of the commands to one instance (D16). */
+export declare const FLEET_COMMAND_TOPIC_PREFIX: string;
+/** Presence topic prefix of a command's reply (D16). */
+export declare const FLEET_REPLY_TOPIC_PREFIX: string;
+/** Presence topic announcing a changed store collection (D16). */
+export declare const ADMIN_CHANGED_TOPIC: string;
+/** Redis key prefix of the admin store (D7). */
+export declare const ADMIN_REDIS_PREFIX: string;
+/** How long a kicked player is refused a fresh join to the same session, in seconds (D12). */
+export declare const KICK_REJOIN_BLOCK_SECONDS: number;
+/** How often a metrics sample is taken, in milliseconds (D22). */
+export declare const METRICS_SAMPLE_INTERVAL_MS: number;
+/** Metrics samples per hour of history (D22). */
+export declare const METRICS_SAMPLES_PER_HOUR: number;
+/** Store lease name of the fleet leader (D24). */
+export declare const LEADER_LEASE_NAME: string;
+/** How long the leader lease lasts without renewal, in milliseconds (D24). */
+export declare const LEADER_LEASE_TTL_MS: number;
+/** How often the leader renews its lease, in milliseconds (D24). */
+export declare const LEADER_RENEW_INTERVAL_MS: number;
+/** How often the leader evaluates alerts, windows and rollouts, in milliseconds (D24). */
+export declare const LEADER_TICK_MS: number;
+/** The PagerDuty Events v2 endpoint alert channels post to (DR §8). */
+export declare const PAGERDUTY_EVENTS_URL: string;
+/** Alert channel request timeout, in milliseconds (D24). */
+export declare const ALERT_CHANNEL_TIMEOUT_MS: number;
+/** Audit retention default, in days (D19). */
+export declare const DEFAULT_AUDIT_RETENTION_DAYS: number;
+/** How often audit retention runs, in milliseconds (D19). */
+export declare const AUDIT_RETENTION_INTERVAL_MS: number;
+/** Default automatic revert of a temporary log level, in minutes (D21). */
+export declare const DEFAULT_LOG_LEVEL_REVERT_MINUTES: number;
+/** Hash chain seed of the first audit record (D19). */
+export declare const AUDIT_CHAIN_SEED: string;
+/** The options a console override may change live (D20); every other option needs a restart (R23). */
+export declare const LIVE_EDITABLE_OPTION_PATHS: string[];
+/** Rows per page of server-side lists. */
+export declare const ADMIN_PAGE_SIZE: number;
+/** How often a console session's lastSeenAt is written, in milliseconds. */
+export declare const SESSION_TOUCH_INTERVAL_MS: number;
+/** How often an API key's lastUsedAt is written, in milliseconds. */
+export declare const API_KEY_TOUCH_INTERVAL_MS: number;
+/** How often expired console sessions and pending sign-ins are swept, in milliseconds. */
+export declare const SESSION_SWEEP_INTERVAL_MS: number;
+/** OpenID discovery cache lifetime, in milliseconds. */
+export declare const OIDC_DISCOVERY_CACHE_MS: number;
+/** How often Colyseus refreshes each Cloud API resource, in seconds; the leader refreshes no faster (colyseus-cloud-console D4). */
+export declare const COLYSEUS_CLOUD_REFRESH_SECONDS: Readonly<Record<CloudResourceName, number>>;
+/** Cloud API request timeout, in milliseconds. */
+export declare const COLYSEUS_CLOUD_TIMEOUT_MS: number;
+/** Seconds to wait after a 429, 5xx or no answer when Retry-After is missing or not a number (Colyseus's polling guide). */
+export declare const COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS: number;
+/** Fewest seconds to wait after a 429, 5xx or no answer. */
+export declare const COLYSEUS_CLOUD_MIN_RETRY_SECONDS: number;
+/** Slack when deciding a resource is due, in milliseconds, so a tick a little early still refreshes. */
+export declare const COLYSEUS_CLOUD_DUE_TOLERANCE_MS: number;
+/** A part counts as stale once its data is older than this many refresh intervals plus COLYSEUS_CLOUD_STALE_GRACE_MS. */
+export declare const COLYSEUS_CLOUD_STALE_REFRESH_MULTIPLIER: number;
+/** Grace beyond the stale multiple, in milliseconds. */
+export declare const COLYSEUS_CLOUD_STALE_GRACE_MS: number;
+/** Fewest milliseconds between two log requests of the fleet (Colyseus allows 2 a minute per team). */
+export declare const COLYSEUS_CLOUD_LOG_INTERVAL_MS: number;
+/** How long a log answer is shared with other askers of the same instance, stream and lines, in milliseconds. */
+export declare const COLYSEUS_CLOUD_SHARED_LOGS_MS: number;
+/** How long one process reuses a deploy's output, in milliseconds (Colyseus refreshes deploys every 15 s). */
+export declare const COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS: number;
+/** How many recent deploys the page lists. */
+export declare const COLYSEUS_CLOUD_DEPLOY_LIMIT: number;
+/** Milliseconds per second, for Colyseus's second-based intervals and Retry-After. */
+export declare const MILLISECONDS_PER_SECOND: number;
+/** Passkey and OIDC challenge lifetime, in milliseconds. */
+export declare const CHALLENGE_LIFETIME_MS: number;
+/** More live players than this on one address marks it as a possible shared proxy (ban confirmation). */
+export declare const SHARED_ADDRESS_PLAYER_THRESHOLD: number;
+/** The newAdminAddress alert looks this many days back. */
+export declare const NEW_ADMIN_ADDRESS_LOOKBACK_DAYS: number;
+/** Longest notice text, in characters. */
+export declare const NOTICE_TEXT_MAX_LENGTH: number;
+/** Resolution of the event-loop delay monitor, in milliseconds. */
+export declare const EVENT_LOOP_MONITOR_RESOLUTION_MS: number;
+/** Length of one dedicated frame statistics bucket, in seconds. */
+export declare const DEDICATED_FRAME_BUCKET_SECONDS: number;
+/** Dedicated frame statistics buckets kept (one hour). */
+export declare const DEDICATED_FRAME_BUCKET_COUNT: number;
+/** Window of a room's traffic rate, in milliseconds. */
+export declare const ROOM_TRAFFIC_WINDOW_MS: number;
+/** Timeout of a room admin call, in milliseconds. */
+export declare const ROOM_CALL_TIMEOUT_MS: number;
+/** Timeout of a dedicated session stop, in milliseconds. */
+export declare const ROOM_STOP_TIMEOUT_MS: number;

package/lib/admin/AdminConstants.js

@@ -0,0 +1,167 @@
+// Constants of the admin console and its API (game-server-admin-console DR §3 and §13 R23). Times are in milliseconds
+// unless the name says otherwise.
+/** URL path of the console app (with its trailing slash, D1). */
+export const CONSOLE_BASE_PATH = "/game-server/admin/";
+/** URL of the console without its trailing slash (the redirect source). */
+export const CONSOLE_ROOT_PATH = "/game-server/admin";
+/** URL path prefix of the console API (D1, D6). */
+export const ADMIN_API_PREFIX = "/game-server/admin/api/";
+/** Largest admin request body read, in bytes (D6). */
+export const ADMIN_MAX_BODY_BYTES = 1048576;
+/** How long a step-up (second factor re-check) stays valid, in milliseconds (D10). */
+export const STEP_UP_WINDOW_MS = 300000;
+/** How long a first-owner setup link stays valid, in milliseconds (D30). */
+export const SETUP_LINK_LIFETIME_MS = 1800000;
+/** How long a half-finished sign-in (password checked, second factor pending) stays valid, in milliseconds. */
+export const PENDING_SIGN_IN_LIFETIME_MS = 300000;
+/** Failed sign-ins of one account within the lockout window that lock it (spec 1). */
+export const ACCOUNT_LOCKOUT_FAILURES = 10;
+/** The lockout counting window and the lock duration, in milliseconds. */
+export const ACCOUNT_LOCKOUT_WINDOW_MS = 900000;
+/** Failed sign-ins from one address within the lockout window before it is refused with 429. */
+export const ADDRESS_SIGN_IN_FAILURES = 30;
+/** Extra delay added per recent failure before a failed sign-in answers, in milliseconds. */
+export const SIGN_IN_DELAY_STEP_MS = 250;
+/** Cap of the failed sign-in delay, in milliseconds. */
+export const SIGN_IN_DELAY_MAX_MS = 2000;
+/** Minimum admin password length (D8). */
+export const MINIMUM_PASSWORD_LENGTH = 12;
+/** Number of one-time recovery codes an account gets (D8). */
+export const RECOVERY_CODE_COUNT = 10;
+/** TOTP time step, in seconds (D8). */
+export const TOTP_STEP_SECONDS = 30;
+/** Digits of a TOTP code (D8). */
+export const TOTP_DIGITS = 6;
+/** Steps before and after the current one a TOTP code may come from (clock skew, D8). */
+export const TOTP_ALLOWED_DRIFT_STEPS = 1;
+/** Bytes of a TOTP secret (D8). */
+export const TOTP_SECRET_BYTES = 20;
+/** scrypt CPU/memory cost N (D8). */
+export const SCRYPT_COST = 16384;
+/** scrypt block size r (D8). */
+export const SCRYPT_BLOCK_SIZE = 8;
+/** scrypt parallelism p (D8). */
+export const SCRYPT_PARALLELISM = 1;
+/** Bytes of a scrypt password hash (D8). */
+export const SCRYPT_KEY_BYTES = 64;
+/** Bytes of a scrypt salt (D8). */
+export const SCRYPT_SALT_BYTES = 16;
+/** How often each instance publishes its heartbeat, in milliseconds (D16). */
+export const FLEET_HEARTBEAT_INTERVAL_MS = 5000;
+/** An instance silent this long is "lost", in milliseconds (D16). */
+export const FLEET_LOST_AFTER_MS = 15000;
+/** A lost instance is forgotten after this long, in milliseconds (D16). */
+export const FLEET_FORGET_AFTER_MS = 600000;
+/** How long a fleet command waits for its reply, in milliseconds (D16). */
+export const FLEET_COMMAND_TIMEOUT_MS = 5000;
+/** Presence hash of the fleet's heartbeats (D16). */
+export const FLEET_INSTANCES_KEY = "bgs:fleet:instances";
+/** Presence topic prefix of the commands to one instance (D16). */
+export const FLEET_COMMAND_TOPIC_PREFIX = "bgs:fleet:command:";
+/** Presence topic prefix of a command's reply (D16). */
+export const FLEET_REPLY_TOPIC_PREFIX = "bgs:fleet:reply:";
+/** Presence topic announcing a changed store collection (D16). */
+export const ADMIN_CHANGED_TOPIC = "bgs:admin:changed";
+/** Redis key prefix of the admin store (D7). */
+export const ADMIN_REDIS_PREFIX = "bgs:admin:";
+/** How long a kicked player is refused a fresh join to the same session, in seconds (D12). */
+export const KICK_REJOIN_BLOCK_SECONDS = 300;
+/** How often a metrics sample is taken, in milliseconds (D22). */
+export const METRICS_SAMPLE_INTERVAL_MS = 15000;
+/** Metrics samples per hour of history (D22). */
+export const METRICS_SAMPLES_PER_HOUR = 240;
+/** Store lease name of the fleet leader (D24). */
+export const LEADER_LEASE_NAME = "fleet-leader";
+/** How long the leader lease lasts without renewal, in milliseconds (D24). */
+export const LEADER_LEASE_TTL_MS = 30000;
+/** How often the leader renews its lease, in milliseconds (D24). */
+export const LEADER_RENEW_INTERVAL_MS = 10000;
+/** How often the leader evaluates alerts, windows and rollouts, in milliseconds (D24). */
+export const LEADER_TICK_MS = 15000;
+/** The PagerDuty Events v2 endpoint alert channels post to (DR §8). */
+export const PAGERDUTY_EVENTS_URL = "https://events.pagerduty.com/v2/enqueue";
+/** Alert channel request timeout, in milliseconds (D24). */
+export const ALERT_CHANNEL_TIMEOUT_MS = 5000;
+/** Audit retention default, in days (D19). */
+export const DEFAULT_AUDIT_RETENTION_DAYS = 365;
+/** How often audit retention runs, in milliseconds (D19). */
+export const AUDIT_RETENTION_INTERVAL_MS = 3600000;
+/** Default automatic revert of a temporary log level, in minutes (D21). */
+export const DEFAULT_LOG_LEVEL_REVERT_MINUTES = 30;
+/** Hash chain seed of the first audit record (D19). */
+export const AUDIT_CHAIN_SEED = "0".repeat(64);
+/** The options a console override may change live (D20); every other option needs a restart (R23). */
+export const LIVE_EDITABLE_OPTION_PATHS = [
+    "logLevel",
+    "limits.allowedOrigins",
+    "limits.allowMissingOrigin",
+    "limits.joinRequestsPerMinutePerAddress",
+    "limits.maxSessions",
+    "limits.maxPlayersPerSession",
+    "limits.maxDedicatedSessions",
+    "limits.maxMessagesPerSecond",
+    "limits.maxSessionNameLength",
+    "drainSeconds",
+    "admin.grafanaUrl"
+];
+/** Rows per page of server-side lists. */
+export const ADMIN_PAGE_SIZE = 50;
+/** How often a console session's lastSeenAt is written, in milliseconds. */
+export const SESSION_TOUCH_INTERVAL_MS = 60000;
+/** How often an API key's lastUsedAt is written, in milliseconds. */
+export const API_KEY_TOUCH_INTERVAL_MS = 60000;
+/** How often expired console sessions and pending sign-ins are swept, in milliseconds. */
+export const SESSION_SWEEP_INTERVAL_MS = 600000;
+/** OpenID discovery cache lifetime, in milliseconds. */
+export const OIDC_DISCOVERY_CACHE_MS = 600000;
+/** How often Colyseus refreshes each Cloud API resource, in seconds; the leader refreshes no faster (colyseus-cloud-console D4). */
+export const COLYSEUS_CLOUD_REFRESH_SECONDS = {
+    applications: 60,
+    metricsCurrent: 30,
+    metricsDay: 600,
+    egress: 600,
+    deploys: 15,
+    billing: 600
+};
+/** Cloud API request timeout, in milliseconds. */
+export const COLYSEUS_CLOUD_TIMEOUT_MS = 10000;
+/** Seconds to wait after a 429, 5xx or no answer when Retry-After is missing or not a number (Colyseus's polling guide). */
+export const COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS = 30;
+/** Fewest seconds to wait after a 429, 5xx or no answer. */
+export const COLYSEUS_CLOUD_MIN_RETRY_SECONDS = 5;
+/** Slack when deciding a resource is due, in milliseconds, so a tick a little early still refreshes. */
+export const COLYSEUS_CLOUD_DUE_TOLERANCE_MS = 1000;
+/** A part counts as stale once its data is older than this many refresh intervals plus COLYSEUS_CLOUD_STALE_GRACE_MS. */
+export const COLYSEUS_CLOUD_STALE_REFRESH_MULTIPLIER = 2;
+/** Grace beyond the stale multiple, in milliseconds. */
+export const COLYSEUS_CLOUD_STALE_GRACE_MS = 30000;
+/** Fewest milliseconds between two log requests of the fleet (Colyseus allows 2 a minute per team). */
+export const COLYSEUS_CLOUD_LOG_INTERVAL_MS = 30000;
+/** How long a log answer is shared with other askers of the same instance, stream and lines, in milliseconds. */
+export const COLYSEUS_CLOUD_SHARED_LOGS_MS = 60000;
+/** How long one process reuses a deploy's output, in milliseconds (Colyseus refreshes deploys every 15 s). */
+export const COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS = 15000;
+/** How many recent deploys the page lists. */
+export const COLYSEUS_CLOUD_DEPLOY_LIMIT = 20;
+/** Milliseconds per second, for Colyseus's second-based intervals and Retry-After. */
+export const MILLISECONDS_PER_SECOND = 1000;
+/** Passkey and OIDC challenge lifetime, in milliseconds. */
+export const CHALLENGE_LIFETIME_MS = 300000;
+/** More live players than this on one address marks it as a possible shared proxy (ban confirmation). */
+export const SHARED_ADDRESS_PLAYER_THRESHOLD = 5;
+/** The newAdminAddress alert looks this many days back. */
+export const NEW_ADMIN_ADDRESS_LOOKBACK_DAYS = 90;
+/** Longest notice text, in characters. */
+export const NOTICE_TEXT_MAX_LENGTH = 500;
+/** Resolution of the event-loop delay monitor, in milliseconds. */
+export const EVENT_LOOP_MONITOR_RESOLUTION_MS = 20;
+/** Length of one dedicated frame statistics bucket, in seconds. */
+export const DEDICATED_FRAME_BUCKET_SECONDS = 15;
+/** Dedicated frame statistics buckets kept (one hour). */
+export const DEDICATED_FRAME_BUCKET_COUNT = 240;
+/** Window of a room's traffic rate, in milliseconds. */
+export const ROOM_TRAFFIC_WINDOW_MS = 5000;
+/** Timeout of a room admin call, in milliseconds. */
+export const ROOM_CALL_TIMEOUT_MS = 5000;
+/** Timeout of a dedicated session stop, in milliseconds. */
+export const ROOM_STOP_TIMEOUT_MS = 30000;

package/lib/admin/AdminCrypto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A random token, URL-safe.
+ * @param byteCount Random bytes in the token.
+ * @returns base64url text.
+ */
+export declare function randomToken(byteCount: number): string;
+/**
+ * The SHA-256 of a text, as stored ids of secrets (session cookies, pending tokens, key secrets).
+ * @param text The text.
+ * @returns Lower-case hex.
+ */
+export declare function sha256Hex(text: string): string;
+/**
+ * Compares two texts in constant time when their lengths are equal.
+ * @param left One text.
+ * @param right The other.
+ * @returns True when equal.
+ */
+export declare function textsMatch(left: string, right: string): boolean;