@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/AdminCli.js

@@ -0,0 +1,351 @@
+// `babylon-game-server admin <command>`: account recovery and key management directly on the admin data store
+// (game-server-admin-console T3, DR §10). Every change is audited as the actor "cli" with processId "cli".
+import { Redis } from "ioredis";
+import { GameServerConfigError, loadGameServerConfig } from "../GameServerConfig.js";
+import { AdminAccounts } from "./AdminAccounts.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { AdminAudit } from "./AdminAudit.js";
+import { SYSTEM_CLOCK } from "./AdminClock.js";
+import { ADMIN_PERMISSIONS, isAdminPermission } from "./AdminPermissions.js";
+import { openAdminStore } from "./AdminStore.js";
+import { ApiKeys } from "./ApiKeys.js";
+import { ConsoleSessions } from "./ConsoleSessions.js";
+/** Exit code of a usage or config problem. */
+const USAGE_EXIT_CODE = 2;
+/** HTTP-style status of an unknown account (AdminRequestError). */
+const HTTP_NOT_FOUND = 404;
+/** Exit code of any other failure. */
+const FAILURE_EXIT_CODE = 1;
+/** The flags passed on to the config loader; every other flag belongs to the command. */
+const CONFIG_FLAGS = new Set(["--config", "--redis-url", "--admin-data-dir"]);
+/** Prefix of a flag. */
+const FLAG_PREFIX = "--";
+/** The process id CLI audit records carry (R32). */
+const CLI_PROCESS_ID = "cli";
+/** Milliseconds per day. */
+const MILLISECONDS_PER_DAY = 86400000;
+/** The character a terminal sends for Enter, and its alternatives. */
+const ENTER_CHARACTERS = new Set(["\r", "\n", "\u0004"]);
+/** The character a terminal sends for Ctrl-C. */
+const INTERRUPT_CHARACTER = "\u0003";
+/** The characters a terminal sends for Backspace. */
+const BACKSPACE_CHARACTERS = new Set(["\u007f", "\b"]);
+/** The help text of the admin command. */
+const USAGE_TEXT = [
+    "usage: babylon-game-server admin <command> [--config <file>] [--redis-url <url>] [--admin-data-dir <folder>]",
+    "  list-users",
+    "  create-owner --username <name> [--display-name <name>] [--password-env <VARIABLE>]",
+    "  reset-password --username <name> [--password-env <VARIABLE>]",
+    "  reset-second-factor --username <name>",
+    "  unlock --username <name>",
+    "  end-sessions --username <name>",
+    "  create-api-key --name <name> --permissions <comma list> [--expires-days <days>]",
+    "  revoke-api-key --key-id <id>"
+].join("\n");
+/** A wrong command line: printed with the usage and exit code 2. */
+class AdminUsageError extends Error {
+    /**
+     * Creates the error.
+     * @param message What is wrong.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AdminUsageError";
+    }
+}
+/** The commands by name. */
+const COMMANDS = {
+    "list-users": listUsers,
+    "create-owner": createOwner,
+    "reset-password": resetPassword,
+    "reset-second-factor": resetSecondFactor,
+    "unlock": unlockUser,
+    "end-sessions": endSessions,
+    "create-api-key": createApiKey,
+    "revoke-api-key": revokeApiKey
+};
+/**
+ * Runs `babylon-game-server admin <command> …` and sets the exit code: 0 on success, 2 on a usage or config problem,
+ * 1 otherwise.
+ * @param argumentList The arguments after `admin`.
+ * @param environment The process environment.
+ */
+export async function runAdminCommand(argumentList, environment) {
+    let redisClient = null;
+    let store = null;
+    try {
+        const commandName = argumentList[0];
+        const command = (commandName != null) ? COMMANDS[commandName] : undefined;
+        if (command == null)
+            throw new AdminUsageError((commandName == null) ? "name a command" : "unknown command " + commandName);
+        const { configArguments, flags } = splitArguments(argumentList.slice(1));
+        const config = await loadGameServerConfig({ argv: configArguments, environment: environment, workingDirectory: process.cwd() });
+        redisClient = (config.redis.url != null) ? new Redis(config.redis.url) : null;
+        store = await openAdminStore(config, redisClient);
+        const sessions = new ConsoleSessions(store, SYSTEM_CLOCK, config.admin.sessionIdleMinutes, config.admin.sessionMaxHours);
+        const context = {
+            flags: flags,
+            environment: environment,
+            store: store,
+            accounts: new AdminAccounts(store, SYSTEM_CLOCK, sessions, false),
+            sessions: sessions,
+            apiKeys: new ApiKeys(store, SYSTEM_CLOCK),
+            audit: new AdminAudit(store, SYSTEM_CLOCK, () => CLI_PROCESS_ID)
+        };
+        await command(context);
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    finally {
+        await store?.close();
+        if (redisClient != null)
+            await redisClient.quit();
+    }
+}
+/**
+ * Prints a failure and sets its exit code.
+ * @param error What went wrong.
+ */
+function reportFailure(error) {
+    if (error instanceof AdminUsageError) {
+        console.error(error.message + "\n" + USAGE_TEXT);
+        process.exitCode = USAGE_EXIT_CODE;
+        return;
+    }
+    if (error instanceof GameServerConfigError) {
+        console.error(error.message);
+        process.exitCode = USAGE_EXIT_CODE;
+        return;
+    }
+    console.error((error instanceof Error) ? error.message : String(error));
+    process.exitCode = FAILURE_EXIT_CODE;
+}
+/**
+ * Splits the arguments into the config flags (for loadGameServerConfig) and the command's own `--name value` flags.
+ * @param argumentList The arguments after the command name.
+ * @returns Both sets.
+ * @throws AdminUsageError for a flag without a value or a stray argument.
+ */
+function splitArguments(argumentList) {
+    const configArguments = [];
+    const flags = new Map();
+    for (let i = 0; i < argumentList.length; i += 2) {
+        const flag = argumentList[i];
+        const value = argumentList[i + 1];
+        if (!flag.startsWith(FLAG_PREFIX))
+            throw new AdminUsageError("unexpected argument " + flag);
+        if (value == null || value.startsWith(FLAG_PREFIX))
+            throw new AdminUsageError(flag + " needs a value");
+        if (CONFIG_FLAGS.has(flag))
+            configArguments.push(flag, value);
+        else
+            flags.set(flag.substring(FLAG_PREFIX.length), value);
+    }
+    return { configArguments: configArguments, flags: flags };
+}
+/**
+ * A required flag of the command.
+ * @param context The command context.
+ * @param name The flag without dashes.
+ * @returns Its value.
+ * @throws AdminUsageError when it is missing.
+ */
+function requiredFlag(context, name) {
+    const value = context.flags.get(name);
+    if (value == null || value === "")
+        throw new AdminUsageError("--" + name + " is required");
+    return value;
+}
+/**
+ * The account a --username flag names.
+ * @param context The command context.
+ * @returns The stored account.
+ * @throws AdminUsageError without --username; AdminRequestError when no such account exists.
+ */
+async function namedUser(context) {
+    const username = requiredFlag(context, "username");
+    const stored = await context.accounts.findByUsername(username);
+    if (stored == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no admin user named " + username);
+    return stored;
+}
+/**
+ * Audits a CLI action.
+ * @param context The command context.
+ * @param action The action.
+ * @param target What it acted on.
+ * @param parameters Its parameters (never secrets).
+ */
+async function auditCli(context, action, target, parameters = {}) {
+    const entry = { actor: { kind: "cli", id: "cli", name: "CLI" }, clientAddress: null, processId: CLI_PROCESS_ID, action: action, target: target, parameters: parameters, result: { ok: true, detail: null } };
+    await context.audit.record(entry);
+}
+/**
+ * The new password: from the variable --password-env names, else typed twice on the terminal with hidden input.
+ * @param context The command context.
+ * @returns The password.
+ * @throws AdminUsageError when neither source is available or the typed passwords differ.
+ */
+async function readNewPassword(context) {
+    const variableName = context.flags.get("password-env");
+    if (variableName != null) {
+        const fromEnvironment = context.environment[variableName];
+        if (fromEnvironment == null || fromEnvironment === "")
+            throw new AdminUsageError("the environment variable " + variableName + " is empty");
+        return fromEnvironment;
+    }
+    if (!process.stdin.isTTY)
+        throw new AdminUsageError("no terminal to type the password in: pass --password-env <VARIABLE>");
+    const first = await promptHidden("New password: ");
+    const second = await promptHidden("Repeat it: ");
+    if (first !== second)
+        throw new AdminUsageError("the two passwords differ");
+    return first;
+}
+/**
+ * Reads one line from the terminal without echoing it.
+ * @param question The prompt.
+ * @returns The typed text.
+ * @throws AdminUsageError when the user presses Ctrl-C.
+ */
+function promptHidden(question) {
+    return new Promise((resolve, reject) => {
+        const input = process.stdin;
+        let typed = "";
+        process.stdout.write(question);
+        input.setRawMode(true);
+        input.resume();
+        input.setEncoding("utf8");
+        const finish = (error) => {
+            input.setRawMode(false);
+            input.pause();
+            input.removeListener("data", onData);
+            process.stdout.write("\n");
+            if (error != null)
+                reject(error);
+            else
+                resolve(typed);
+        };
+        const onData = (chunk) => {
+            for (const character of chunk) {
+                if (ENTER_CHARACTERS.has(character)) {
+                    finish(null);
+                    return;
+                }
+                if (character === INTERRUPT_CHARACTER) {
+                    finish(new AdminUsageError("cancelled"));
+                    return;
+                }
+                if (BACKSPACE_CHARACTERS.has(character))
+                    typed = typed.slice(0, -1);
+                else
+                    typed += character;
+            }
+        };
+        input.on("data", onData);
+    });
+}
+/**
+ * `list-users`: one line per account.
+ * @param context The command context.
+ */
+async function listUsers(context) {
+    const users = await context.store.listDocuments("users");
+    users.sort((left, right) => left.value.username.localeCompare(right.value.username));
+    if (users.length === 0)
+        console.log("no admin users");
+    for (const stored of users) {
+        const user = stored.value;
+        const states = [];
+        if (user.disabled)
+            states.push("disabled");
+        if (context.accounts.isLocked(user))
+            states.push("locked");
+        states.push((user.totpSecret != null) ? "second factor enrolled" : "second factor not enrolled");
+        console.log(user.username + "\t" + user.role + "\t" + user.displayName + "\t" + states.join(", "));
+    }
+}
+/**
+ * `create-owner`: an owner who enrols an authenticator at the first sign-in.
+ * @param context The command context.
+ */
+async function createOwner(context) {
+    const username = requiredFlag(context, "username");
+    const password = await readNewPassword(context);
+    const owner = await context.accounts.createUser({ username: username, displayName: context.flags.get("display-name") ?? "", email: null, role: "owner", password: password, oidcSubject: null });
+    await auditCli(context, "user.create", owner.username, { role: "owner" });
+    console.log("created owner " + owner.username + "; sign in at /game-server/admin/ to enrol an authenticator");
+}
+/**
+ * `reset-password`: sets a new password and ends the account's sessions.
+ * @param context The command context.
+ */
+async function resetPassword(context) {
+    const stored = await namedUser(context);
+    await context.accounts.setPassword(stored, await readNewPassword(context));
+    await context.sessions.endAllFor(stored.id);
+    await auditCli(context, "user.resetPassword", stored.value.username);
+    console.log("password reset for " + stored.value.username);
+}
+/**
+ * `reset-second-factor`: the account enrols a new authenticator at its next sign-in.
+ * @param context The command context.
+ */
+async function resetSecondFactor(context) {
+    const stored = await namedUser(context);
+    await context.accounts.resetSecondFactor(stored.id);
+    await context.sessions.endAllFor(stored.id);
+    await auditCli(context, "user.resetSecondFactor", stored.value.username);
+    console.log("second factor reset for " + stored.value.username);
+}
+/**
+ * `unlock`: clears a lockout.
+ * @param context The command context.
+ */
+async function unlockUser(context) {
+    const stored = await namedUser(context);
+    await context.accounts.unlock(stored.id);
+    await auditCli(context, "user.unlock", stored.value.username);
+    console.log("unlocked " + stored.value.username);
+}
+/**
+ * `end-sessions`: signs the account out everywhere.
+ * @param context The command context.
+ */
+async function endSessions(context) {
+    const stored = await namedUser(context);
+    const ended = await context.sessions.endAllFor(stored.id);
+    await auditCli(context, "user.endSessions", stored.value.username, { ended: ended });
+    console.log("ended " + ended + " session(s) of " + stored.value.username);
+}
+/**
+ * `create-api-key`: prints the secret once.
+ * @param context The command context.
+ * @throws AdminUsageError for an unknown permission or a bad expiry.
+ */
+async function createApiKey(context) {
+    const name = requiredFlag(context, "name");
+    const permissionNames = requiredFlag(context, "permissions").split(",").map((permission) => permission.trim()).filter((permission) => permission !== "");
+    const unknown = permissionNames.find((permission) => !isAdminPermission(permission));
+    if (unknown != null)
+        throw new AdminUsageError("unknown permission " + unknown + " (known: " + ADMIN_PERMISSIONS.join(", ") + ")");
+    const expiresDaysText = context.flags.get("expires-days");
+    const expiresDays = (expiresDaysText != null) ? Number(expiresDaysText) : null;
+    if (expiresDays != null && !(Number.isFinite(expiresDays) && expiresDays > 0))
+        throw new AdminUsageError("--expires-days must be a number of days above 0");
+    const expiresAt = (expiresDays != null) ? new Date(Date.now() + expiresDays * MILLISECONDS_PER_DAY).toISOString() : null;
+    const created = await context.apiKeys.create({ name: name, permissions: permissionNames, expiresAt: expiresAt, allowedNetworks: [] }, CLI_PROCESS_ID, new Set(ADMIN_PERMISSIONS));
+    await auditCli(context, "apiKey.create", created.record.name, { keyId: created.record.keyId, permissions: created.record.permissions });
+    console.log("key id: " + created.record.keyId);
+    console.log("secret (shown once): " + created.secret);
+}
+/**
+ * `revoke-api-key`.
+ * @param context The command context.
+ */
+async function revokeApiKey(context) {
+    const revoked = await context.apiKeys.revoke(requiredFlag(context, "key-id"));
+    await auditCli(context, "apiKey.revoke", revoked.name, { keyId: revoked.keyId });
+    console.log("revoked key " + revoked.keyId);
+}

package/lib/admin/AdminClock.d.ts

@@ -0,0 +1,51 @@
+/** Time and timers, as the admin services use them. */
+export interface AdminClock {
+    /**
+     * The current time.
+     * @returns Milliseconds since the Unix epoch.
+     */
+    now(): number;
+    /**
+     * Runs a callback once after a delay.
+     * @param callback What to run.
+     * @param delayMs The delay, in milliseconds.
+     * @returns A handle for clearTimeout.
+     */
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    /**
+     * Cancels a setTimeout.
+     * @param handle The handle setTimeout returned.
+     */
+    clearTimeout(handle: unknown): void;
+    /**
+     * Runs a callback repeatedly.
+     * @param callback What to run.
+     * @param intervalMs The interval, in milliseconds.
+     * @returns A handle for clearInterval.
+     */
+    setInterval(callback: () => void, intervalMs: number): unknown;
+    /**
+     * Cancels a setInterval.
+     * @param handle The handle setInterval returned.
+     */
+    clearInterval(handle: unknown): void;
+}
+/** GameServerOptions.adminTesting: values only tests replace (R10). */
+export interface AdminTestingOptions {
+    /** The clock of every admin timer (default: the system clock). */
+    clock?: AdminClock;
+    /** Milliseconds between fleet heartbeats (default FLEET_HEARTBEAT_INTERVAL_MS). */
+    heartbeatIntervalMs?: number;
+    /** Milliseconds between metrics samples (default METRICS_SAMPLE_INTERVAL_MS). */
+    metricsSampleIntervalMs?: number;
+    /** Milliseconds between leader ticks (default LEADER_TICK_MS). */
+    leaderTickMs?: number;
+    /** The PagerDuty Events v2 URL alert channels post to (default the real one). */
+    pagerDutyUrl?: string;
+    /** Called after each Colyseus Cloud refresh pass of the leader, with the clock time it ran at (colyseus-cloud-console D17). */
+    colyseusCloudRefreshed?: (nowMilliseconds: number) => void;
+    /** Milliseconds between leaderboard scheduler ticks (default LEADERBOARD_SCHEDULER_TICK_MS). */
+    leaderboardSchedulerTickMs?: number;
+}
+/** The real clock: Date.now and the global timers. Its timers never keep the process alive. */
+export declare const SYSTEM_CLOCK: AdminClock;

package/lib/admin/AdminClock.js

@@ -0,0 +1,10 @@
+// The clock every admin timer and every "now" goes through (game-server-admin-console DR §13 R10), so tests can move
+// time with a manual clock instead of waiting.
+/** The real clock: Date.now and the global timers. Its timers never keep the process alive. */
+export const SYSTEM_CLOCK = {
+    now: () => Date.now(),
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs).unref(),
+    clearTimeout: (handle) => clearTimeout(handle),
+    setInterval: (callback, intervalMs) => setInterval(callback, intervalMs).unref(),
+    clearInterval: (handle) => clearInterval(handle)
+};

package/lib/admin/AdminConsole.d.ts

@@ -0,0 +1,39 @@
+import { type Endpoint } from "colyseus";
+import type { AdminCoreServices } from "./AdminServices.js";
+/** The web console and its API, as GameServer.ts uses them. */
+export interface AdminConsole {
+    /**
+     * The router entries of the app and the API.
+     * @returns The endpoints, keyed for createRouter.
+     */
+    routes(): Record<string, Endpoint>;
+    /**
+     * The router's onRequest hook: answers GET /game-server/admin with a 308 to /game-server/admin/. The router keeps
+     * both paths on one node and 404s whichever does not match the first route's trailing slash, so this redirect
+     * cannot be an endpoint of its own.
+     * @param request The incoming request.
+     * @returns The redirect, or undefined to let the router go on.
+     */
+    redirectBarePath(request: Request): Response | undefined;
+    /** Starts the console's timers; call after listen. */
+    start(): Promise<void>;
+    /** Stops the console's timers; call before the server shuts down (R4). */
+    stop(): Promise<void>;
+    /**
+     * Whether the API answers (R6): admin.console on and a user, a pending setup or admin.token.
+     * @returns True when it answers.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Appends a server event of this instance to the activity feed (the certificate reload, T14).
+     * @param text What happened.
+     */
+    recordServerEvent(text: string): void;
+}
+/**
+ * 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 declare function createAdminConsole(core: AdminCoreServices): Promise<AdminConsole>;